Skip to main content

Documentation Index

Fetch the complete documentation index at: https://operativusai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The synchronous run endpoint executes an agent and blocks until the agent produces a final response. This is the simplest way to integrate Agent Manager — send a message, receive the full answer. For long-running tasks or streaming output, see Background Runs and SSE Streaming. All requests require a valid bearer token in the Authorization header.

​
Execute a synchronous run

POST /api/agents/{agentId}/runs
Runs the agent against the provided message and returns a RunResponse when execution completes. If the agent triggers a Human-in-the-Loop (HITL) tool during execution, the run is suspended and the response returns with status: "PAUSED" — call the continue endpoint to approve or reject.

​
Path parameters

​
agentId
string
required
The unique identifier of the agent to run. Retrieve valid IDs from GET /api/agents.

​
Request body

​
message
string
required
The user’s input or query. The agent uses this as the primary prompt for the interaction.
​
sessionId
string
A UUID identifying an existing conversation session. When provided, the agent rehydrates its message history from that session, enabling multi-turn conversations. Omit to start a new session — the server generates and returns a new sessionId.
​
userId
string
Associates this run with a specific user. Used for memory scoping, audit logs, and per-user analytics. Defaults to the authenticated principal when omitted.
​
orgId
string
Tenant identifier for multi-tenant deployments. Scopes the run to a specific organization’s agents and knowledge bases.
​
generateFollowups
boolean
default:"false"
When true, the agent generates a list of suggested follow-up questions to append to the response. Useful for chat UIs that want to prompt the next turn.
​
media
object[]
An array of multimodal media inputs for vision-capable agents.
​
options
object
Optional RunOptions object to override model-level settings for this specific run.

​
Response

​
runId
string
required
Unique identifier for this specific run. Use this ID to call the continue or cancel endpoints.
​
sessionId
string
required
The conversation session associated with this run. Pass this value back in subsequent requests to maintain conversation context.
​
content
string
The agent’s final answer, rendered as Markdown. Empty when status is "FAILED" or "PAUSED".
​
metadata
object
Usage statistics and model information for this run.
​
tools
object[]
An ordered list of tool calls made during execution. Useful for audit logs and debugging.
​
reasoningSteps
string[]
Captured inner thoughts from the agent’s reasoning process — what the agent was thinking before each tool call. Useful for explainability and debugging.
​
status
string
required
Execution status of the run. One of:
  • "COMPLETED" — the agent finished successfully and content contains the response.
  • "FAILED" — an unrecoverable error occurred during execution.
  • "PAUSED" — the agent triggered a Human-in-the-Loop confirmation gate. Call /runs/{runId}/continue to resume.
curl --request POST \
  --url "http://localhost:8080/api/agents/finance_agent/runs" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "What is the current stock price of NVIDIA?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "user_abc123",
    "generateFollowups": true
  }'
Example response 
{
  "runId": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "The current stock price of NVIDIA (NVDA) is **$875.40**, up 2.3% today.\n\n**Suggested follow-ups:**\n- How does NVDA compare to AMD this quarter?\n- What is NVIDIA's P/E ratio?",
  "metadata": {
    "model": "gpt-4o",
    "promptTokens": 342,
    "completionTokens": 89,
    "totalTokens": 431
  },
  "tools": [
    {
      "name": "get_stock_price",
      "arguments": { "ticker": "NVDA" },
      "result": "875.40"
    }
  ],
  "reasoningSteps": [
    "The user wants the current NVDA stock price. I should call get_stock_price with ticker=NVDA."
  ],
  "status": "COMPLETED"
}

​
Resume a paused run (HITL)

POST /api/agents/{agentId}/runs/{runId}/continue
When a run returns status: "PAUSED", the agent has encountered a tool marked as requiring human approval (for example, delete_database or send_email). Use this endpoint to approve or reject the pending action.
Until you call this endpoint, the paused run holds its state in the database and is consuming a slot in the job queue. Approve or reject promptly to avoid stale runs.

​
Path parameters

​
agentId
string
required
The agent that owns the paused run.
​
runId
string
required
The run ID returned in the original RunResponse with status: "PAUSED".

​
Request body

​
action
string
required
The human decision. Must be "APPROVE" to allow the tool to execute, or "REJECT" to cancel the tool call and return control to the agent.
curl --request POST \
  --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12/continue" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{ "action": "APPROVE" }'
Example response The server returns a new RunResponse reflecting the outcome after the approved or rejected tool call resolves. 
{
  "runId": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "content": "The database deletion has been approved and completed successfully.",
  "metadata": { "model": "gpt-4o", "totalTokens": 512 },
  "tools": [],
  "reasoningSteps": [],
  "status": "COMPLETED"
}

​
Cancel a run

DELETE /api/agents/{agentId}/runs/{runId}
Sends a cancellation signal to an active or paused run. Returns 204 No Content on success. The run status is updated to CANCELLED in the database.
​
agentId
string
required
The agent that owns the run.
​
runId
string
required
The unique run identifier to cancel.
curl --request DELETE \
  --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12" \
  --header "Authorization: Bearer {token}"
Returns 204 No Content with an empty body on success.
Use the cancel endpoint to clean up PAUSED runs that you no longer intend to approve, freeing queue capacity.