> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an Agent Synchronously — API Reference

> Execute an agent synchronously and receive the complete RunResponse in one request, with built-in HITL pause/resume and cancellation support.

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](/api/agents/background) and [SSE Streaming](/api/agents/stream).

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](#resume-a-paused-run-hitl) to approve or reject.

### Path parameters

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to run. Retrieve valid IDs from `GET /api/agents`.
</ParamField>

### Request body

<ParamField body="message" type="string" required>
  The user's input or query. The agent uses this as the primary prompt for the interaction.
</ParamField>

<ParamField body="sessionId" type="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`.
</ParamField>

<ParamField body="userId" type="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.
</ParamField>

<ParamField body="orgId" type="string">
  Tenant identifier for multi-tenant deployments. Scopes the run to a specific organization's agents and knowledge bases.
</ParamField>

<ParamField body="generateFollowups" type="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.
</ParamField>

<ParamField body="media" type="object[]">
  An array of multimodal media inputs for vision-capable agents.

  <Expandable title="MediaInput fields">
    <ParamField body="type" type="string" required>
      MIME type of the media, e.g. `"image/png"`, `"image/jpeg"`, or `"audio/wav"`.
    </ParamField>

    <ParamField body="data" type="string" required>
      Either a base64-encoded string of the raw media bytes, or an HTTP/HTTPS URL pointing to the media resource.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="options" type="object">
  Optional `RunOptions` object to override model-level settings for this specific run.

  <Expandable title="RunOptions fields">
    <ParamField body="options.model" type="string">
      Override the default model for this run (e.g., `"gpt-4o"`, `"claude-3-5-sonnet"`).
    </ParamField>

    <ParamField body="options.temperature" type="number">
      Sampling temperature, between 0 and 2. Higher values produce more creative responses.
    </ParamField>

    <ParamField body="options.maxTokens" type="number">
      Maximum number of tokens to generate in the response.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="runId" type="string" required>
  Unique identifier for this specific run. Use this ID to call the continue or cancel endpoints.
</ResponseField>

<ResponseField name="sessionId" type="string" required>
  The conversation session associated with this run. Pass this value back in subsequent requests to maintain conversation context.
</ResponseField>

<ResponseField name="content" type="string">
  The agent's final answer, rendered as Markdown. Empty when `status` is `"FAILED"` or `"PAUSED"`.
</ResponseField>

<ResponseField name="metadata" type="object">
  Usage statistics and model information for this run.

  <Expandable title="metadata fields">
    <ResponseField name="model" type="string">
      The model identifier used for this run.
    </ResponseField>

    <ResponseField name="promptTokens" type="number">
      Number of tokens consumed by the input prompt.
    </ResponseField>

    <ResponseField name="completionTokens" type="number">
      Number of tokens generated in the response.
    </ResponseField>

    <ResponseField name="totalTokens" type="number">
      Sum of `promptTokens` and `completionTokens`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tools" type="object[]">
  An ordered list of tool calls made during execution. Useful for audit logs and debugging.

  <Expandable title="ToolCall fields">
    <ResponseField name="name" type="string">
      The name of the tool that was called.
    </ResponseField>

    <ResponseField name="arguments" type="object">
      The arguments passed to the tool.
    </ResponseField>

    <ResponseField name="result" type="string">
      The output returned by the tool.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reasoningSteps" type="string[]">
  Captured inner thoughts from the agent's reasoning process — what the agent was thinking before each tool call. Useful for explainability and debugging.
</ResponseField>

<ResponseField name="status" type="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.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

### Path parameters

<ParamField path="agentId" type="string" required>
  The agent that owns the paused run.
</ParamField>

<ParamField path="runId" type="string" required>
  The run ID returned in the original `RunResponse` with `status: "PAUSED"`.
</ParamField>

### Request body

<ParamField body="action" type="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.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```
</CodeGroup>

**Example response**

The server returns a new `RunResponse` reflecting the outcome after the approved or rejected tool call resolves.

```json theme={null}
{
  "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.

<ParamField path="agentId" type="string" required>
  The agent that owns the run.
</ParamField>

<ParamField path="runId" type="string" required>
  The unique run identifier to cancel.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12" \
    --header "Authorization: Bearer {token}"
  ```
</CodeGroup>

Returns `204 No Content` with an empty body on success.

<Tip>
  Use the cancel endpoint to clean up PAUSED runs that you no longer intend to approve, freeing queue capacity.
</Tip>