The Headless Agent Trigger API lets you run Mattr agents without a UI. By triggering agents from your backend, workflows, or system events, you can treat them as background workers or programmatically called functions.
Quick Start: Your First Trigger
Identify the Agent : Obtain the unique agentId for the agent you wish to execute.
Authenticate : Generate an Agent API Key and Secret in the Authentication tab of your Agent Config.
Prepare the Request : Set your headers with x-api-key and x-api-key-secret.
Execute : Send a POST request with a message to start the run.
Copy {
"message": "Summarize the attached document"
}
Copy https://api-builder-dev.uptiq.dev Authentication is required for all requests
How It Works (At a Glance)
Every agent execution is triggered in one of two ways:
Start a new execution using a message
Resume an existing execution using resume data
Everything else—payloads, documents, reasoning mode—is optional control.
Each request must include exactly one authentication method .
Option 1: Agent API Key (Server-to-Server)
Recommended for backend and service-to-service integrations.
How to get keys
Open your agent’s Agent Config
Go to the Authentication tab
Create an Agent API Key and Secret
Used for first-party or widget-based integrations.
Triggering an Agent
Path Parameters
Unique ID of the agent to execute
Every request must include at least one of the following:
message → start a new execution
resumeData → resume an existing execution
If both are missing, the request fails.
Error
{ "error": "Message or resume data is required" }
Minimal Execution
Start a new agent run using a simple instruction.
{
"message": "Summarize the attached document"
}
Passing Structured Data (Payload)
You can pass structured data alongside a message.
{
"message": "Generate quarterly report",
"payload": {
"quarter": "Q4",
"year": 2024
}
}
When a payload is provided, the agent automatically receives:
The natural language instruction
The structured data context
This is useful for system-driven workflows and data-backed tasks.
Attaching Documents
Agents can read documents during execution.
Common use cases:
Risk or compliance checks
{
"message": "Analyze financial risk",
"documents": [
{
"signedUrl": "<signed-url>",
"fileName": "balance-sheet.pdf",
"mimeType": "application/pdf"
}
]
}
They are acknowledged at execution start
They can influence reasoning, retrieval, or summarization
Resuming an Execution
If an agent's execution pauses or fails, you can resume it rather than starting over.
{
"resumeData": {
"lastStep": "analysis"
},
"executionId": "exec_123"
}
This allows agents to:
Continue from a known step
Avoid reprocessing large inputs
Recover gracefully from interruptions
By default, agent execution is asynchronous.
Async (Default)
Best for long-running or background taskstask
The request returns immediately
Waits for the agent to finish
Useful for real-time UI or immediate responses
{
"message": "Check eligibility",
"executionMode": "sync"
}
Choosing How the Agent Thinks
You can control how much reasoning power the agent uses with options.mode.
{
"options": {
"mode": "balanced"
}
}
Available Modes
Complex reasoning, multi-step logic, high accuracy
Best balance of speed, cost, and intelligence
Simple question–answer tasks
Full client-controlled reasoning
You usually don’t need to set this—the default works well for most use cases.
Model Selection (Optional)
When using qa or custom mode, you can explicitly choose a reasoning model.
{
"options": {
"mode": "qa"
},
"agentStrategy": {
"reasoningModelId": "your-model-id"
}
}
If no model is provided, the system selects one automatically.
How Models Are Chosen (Behind the Scenes)
Mattr dynamically selects the best available reasoning model based on:
Environment configuration
If a configured model is unavailable, the system automatically falls back to a safe alternative.
Model resolution never blocks execution.
Advanced Strategy Configuration
You can override execution strategies when needed.
{
"options": {
"strategyConfig": {
"initialStrategy": "IntelligentPlanner",
"autoSelectStrategy": false,
"allowStrategySwitch": false
}
}
}
If not provided, sensible defaults are applied automatically.
Full Request Schema
{
"message": "string",
"resumeData": {},
"payload": {},
"documents": [],
"context": "string",
"executionId": "string",
"executionMode": "async | sync",
"options": {
"mode": "advanced | balanced | qa | custom",
"runInlineEvaluation": true,
"strategyConfig": {
"initialStrategy": "IntelligentPlanner",
"autoSelectStrategy": false,
"allowStrategySwitch": false
}
},
"agentStrategy": {
"reasoningModelId": "string"
}
}
{
"executionId": "exec_123"
}
Response content may vary based on agent behavior and execution mode.
400 – Validation Error
{ "error": "Message or resume data is required" }
401 – Unauthorized
{ "error": "Invalid or missing agent API key" }
403 – Forbidden
{
"message": "You're not authorized to perform this action.",
"requestId": "<execution-id>"
}
500 – Internal Server Error
{
"message": "Something went wrong. Please try again later.",
"requestId": "<execution-id>"
}
Operational Notes
Execution is asynchronous by default
Execution IDs are auto-generated if not provided
Optional fields are safely defaulted server-side
This endpoint is not idempotent
Model selection is dynamic and fault-tolerant
