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

# Messaging & Events

> Stream assist-mode replies, read the session timeline, respond to tool calls, and cancel runs

## Send Message (Assist Mode)

```http theme={null}
POST /api/v1/managed-agents/sessions/{sessionId}/messages
```

Sends a user message into the session and streams the agent's reply back as **Server-Sent Events**.

<ParamField body="message" type="string" required>
  The user message.
</ParamField>

<ParamField body="model" type="string">
  Override the model configured on the agent for this turn only.
</ParamField>

### Response

```http theme={null}
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```

The stream carries a sequence of JSON events covering turn-run state changes, incremental text/token chunks, and tool calls made by the agent as it works.

<RequestExample>
  ```javascript Streaming client theme={null}
  const response = await fetch(
    `https://suite.sundaypyjamas.com/api/v1/managed-agents/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ message: 'What did you find in the report?' }),
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));
  }
  ```
</RequestExample>

<Warning>
  Returns `400` with `"message is required"` if `message` is missing. Returns `429` if the workspace has hit its managed-agent rate limit.
</Warning>

***

## Get Session Timeline

```http theme={null}
GET /api/v1/managed-agents/sessions/&#123;sessionId&#125;/events
```

Returns the full ordered history of a session — messages and turn runs interleaved, sorted ascending by `created_at`.

<ResponseField name="events" type="(MessageEvent | TurnRunEvent)[]">
  <Expandable title="MessageEvent">
    <ResponseField name="type" type="string">`"message"`</ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="role" type="string">`user` · `assistant` · `tool`</ResponseField>

    <ResponseField name="content" type="string" />

    <ResponseField name="metadata" type="object" />

    <ResponseField name="created_at" type="string" />
  </Expandable>

  <Expandable title="TurnRunEvent">
    <ResponseField name="type" type="string">`"turn_run"`</ResponseField>

    <ResponseField name="id" type="string" />

    <ResponseField name="status" type="string" />

    <ResponseField name="created_at" type="string" />

    <ResponseField name="completed_at" type="string | null" />

    <ResponseField name="error_message" type="string | null" />
  </Expandable>
</ResponseField>

***

## Submit Tool Results

```http theme={null}
POST /api/v1/managed-agents/sessions/&#123;sessionId&#125;/tool-results
```

When an agent needs to call a tool your integration owns, it pauses and emits a pending tool call in the event stream. Execute the tool on your side, then report the result back here so the agent can continue.

<ParamField body="toolCallId" type="string" required>
  The ID of the pending tool call, taken from the event stream.
</ParamField>

<ParamField body="result" type="any">
  The tool's return value. Provide this on success.
</ParamField>

<ParamField body="error" type="string">
  Error message if the tool failed. Provide either `result` or `error`, not both.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://suite.sundaypyjamas.com/api/v1/managed-agents/sessions/sess_44bc.../tool-results \
    -H "Authorization: Bearer spj_ai_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{ "toolCallId": "tc_991a...", "result": { "status": "ok", "rows": 12 } }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "accepted": true,
    "sessionId": "sess_44bc...",
    "toolCallId": "tc_991a...",
    "status": "completed"
  }
  ```
</ResponseExample>

<Warning>
  Returns `403` with `"toolCallId does not belong to session"` if the tool call belongs to a different session, and `404` with `"Unknown toolCallId"` if it doesn't exist.
</Warning>

***

## Cancel Run

```http theme={null}
POST /api/v1/managed-agents/sessions/&#123;sessionId&#125;/cancel
```

<ParamField body="runId" type="string" required>
  The turn run (or [autonomous run](/api-reference/agents/runs)) to cancel.
</ParamField>

<ResponseExample>
  ```json Response theme={null}
  {
    "runId": "run_8a21...",
    "status": "cancelled"
  }
  ```
</ResponseExample>

<Warning>
  Returns `400` with `"Run is {current_status}"` if the run isn't currently running (e.g. already completed).
</Warning>