Skip to main content
GET
/
agents
/
conversations
/
{id}
Get an agent conversation
curl --request GET \
  --url https://api-dev.narrative.io/agents/conversations/{id} \
  --header 'Authorization: Bearer <token>'
{
  "id": "bc2505b7-068d-44ed-8055-a6f6ffe54ab1",
  "company_id": 1,
  "user_id": 407,
  "defaults": {
    "model": "anthropic.claude-opus-4.6",
    "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
    "execution_cluster": "shared",
    "compute_pool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "max_iterations": 8,
    "max_tokens": 2048,
    "temperature": 0,
    "output_format_schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "text"
      ],
      "properties": {
        "text": {
          "type": "string"
        }
      }
    },
    "mcp_servers": [],
    "client_tools": []
  },
  "version": 4,
  "created_at": "2026-05-18T13:21:30.355180Z",
  "updated_at": "2026-05-18T13:21:51.983952Z",
  "name": "<string>",
  "system_prompt": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.narrative.io/llms.txt

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

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
string<uuid>
required

The conversation's UUID. UUID identifying a conversation. Returned from POST /agents/conversations and used in every other agent endpoint that operates on this conversation.

Example:

"bc2505b7-068d-44ed-8055-a6f6ffe54ab1"

Response

The conversation row.

The conversation row as the API returns it. The same shape comes back from POST /agents/conversations (201 Created) and GET /agents/conversations/{id} (200 OK).

​
id
string<uuid>
required

UUID identifying a conversation. Returned from POST /agents/conversations and used in every other agent endpoint that operates on this conversation.

Example:

"bc2505b7-068d-44ed-8055-a6f6ffe54ab1"

​
company_id
integer
required

Company ID derived from the bearer token. Pinned for the conversation's lifetime.

Example:

1

​
user_id
integer
required

User ID derived from the bearer token. Pinned for the conversation's lifetime.

Example:

407

​
defaults
object
required

The configuration applied to every run on this conversation by default. Each field can be overridden per-run via config_override on the POST .../runs body, except system_prompt which is fixed at conversation creation time.

For mcp_servers and client_tools, overrides replace the whole list, not individual entries. There is no per-server or per-tool merge — set the complete catalog you want for that run.

​
version
integer
required

Monotonic per-conversation counter, bumped by 1 (or more) every time a successful run appends messages. Two roles:

  1. Delta cursor for GET .../messages?since=N — fetch only messages with sequence_no > N.
  2. Compare-and-swap token for POST .../runs — set expected_version to the conversation's current head; if it doesn't match at run-creation time, you get a Version Conflict (HTTP 409).

Always start a new run cycle by reading the current version from GET /agents/conversations/{id} rather than caching a value from earlier.

Required range: x >= 0
Example:

4

​
created_at
string<date-time>
required
Example:

"2026-05-18T13:21:30.355180Z"

​
updated_at
string<date-time>
required
Example:

"2026-05-18T13:21:51.983952Z"

​
name
string | null
​
system_prompt
string | null