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": [],
    "tools": []
  },
  "version": 4,
  "created_at": "2026-05-18T13:21:30.355180Z",
  "updated_at": "2026-05-18T13:21:51.983952Z",
  "name": "<string>",
  "system_prompt": "<string>"
}

Agent Conversations

Get an agent conversation

Fetches the conversation’s metadata plus its current version. Use the version immediately before posting a run as expected_version — that’s how the platform’s compare-and-swap guard knows whether the conversation has advanced since you last looked.

When to call this

Before starting a new run: read version, post it as expected_version. If you cache the value across long delays you’ll hit Version Conflict more often.
When resuming a requires_action run: the conversation’s version has advanced because the assistant turn was persisted on the run row’s finalize. Re-read it before posting tool_outputs.
To inspect a conversation’s defaults if you’ve forgotten what was pinned.

What you cannot do here

There is no PATCH / PUT for conversations. The system_prompt and defaults are immutable at the conversation level. To change behavior, override per-run via config_override, or create a new conversation.

Scope: per-user, not per-company

Conversations are scoped to the (company_id, user_id) pair that created them. Peers in the same company cannot see each other’s conversations — the endpoint returns 404 for “does not exist”, “belongs to a different company”, and “belongs to a different user in the same company” alike. This is deliberate: distinguishing them would leak existence.

Permission

agent_conversations resource with read verb.

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": [],
    "tools": []
  },
  "version": 4,
  "created_at": "2026-05-18T13:21:30.355180Z",
  "updated_at": "2026-05-18T13:21:51.983952Z",
  "name": "<string>",
  "system_prompt": "<string>"
}

Authorizations

Authorization

string

header

required

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

Path Parameters

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).

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 and gates every subsequent read endpoint — only the originating user can fetch the conversation, its messages, or its runs. Peers in the same company see 404.

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

Show child attributes

version

integer

required

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

Delta cursor for GET .../messages?since=N — fetch only messages with sequence_no > N.
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

Create an agent conversation List conversation messages (delta read by version cursor)

⌘I