API reference

Agent

Last updated:

Sessions and thread history for the Cardog agent

These routes are not mounted on api.cardog.app yet.
POST/v2/agent/sessionsince 2026-10-27

Open an agent session

Mint a short-lived session for the Cardog agent: a signed grant naming who the session acts as, which tools it may see and the ledger a turn debits. Costs 0 credits. Present `token` as the `grant` query parameter when you open the agent socket, and mint a new one on every connect; it lives 120 seconds. The grant is minted from the credential you send: a signed-in session opens a personal session, an API key opens one billed to that key, an anonymous session opens an anonymous one, and an org token from an organization workspace opens an org session. An organization key, or a server with no person behind it, is 403. Tool reads inside a turn run as the grant's subject and are never billed; the turn is the only charge.

Request body

AgentSessionCreateRequest
surface"web" | "org" | "native" | "mcp" | "sdk"optional

The surface opening the session: "web" (the consumer site), "org" (an organization workspace), "native" (the mobile app), "mcp" (an MCP server), "sdk" (a program using an API key). Defaults to "sdk".

contextobjectoptional
hiddenstring[]optional

Tools the person chose to hide. A hide list only: it never shows a tool the grant does not hold.

orgTokenstringoptional

The org token from the organization workspace (a short-lived credential the API minted from your membership). Present it to open an org session; omit it for a personal one.

curl -X POST "https://api.cardog.app/v2/agent/session" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26" \
  -H "content-type: application/json" \
  -d '{"surface":"sdk"}'

Response

200AgentSession
tokenstring

The signed session. Present it as the grant query parameter on the agent socket, or in the X-Cardog-Agent-Grant header on a thread read. It expires with the grant; mint a new one on every connect.

grantobject
substring

The account the session acts as. Every tool read inside a turn runs as this subject.

kind"anonymous" | "user" | "org" | "key"

"anonymous": an anonymous session (no account yet). "user": a signed-in person. "org": a member inside an organization workspace, minted only from an org token. "key": the owner of a personal API key.

classstringoptional

The organization's class ("oem", "gov", "dealer", "insurer", "fleet", "internal"), or "technician" for a session at the bench. Present when kind is "org".

rolestringoptional

The member's role at mint time. Present when kind is "org".

tenantIdstringoptional

The tenant key, e.g. "oem/example". Present when kind is "org".

orgIdstringoptional

The organization id. Present when kind is "org".

orgSlugstringoptional

The workspace slug in the org surface's URL. Present when kind is "org".

orgNamestringoptional

The organization's display name. Present when kind is "org".

scopesstring[]

The tool scopes the session holds, e.g. ["consumer"] or ["org:*", "org:oem"]. A tool outside them is absent, not refused.

creditobject

The ledger a turn debits

channel"session" | "key" | "org"

"session": the person's own account (an anonymous session has no credit account and is bounded by a turn limit). "key": the API key the session was opened with. "org": the organization.

refstring

The account on that channel: the user id for a session, the key id for a key, the organization id for an org

model"default" | "fixture"

The model chain the session runs on. "default": the conversation chain. "fixture": the scripted sample model, which answers every tool from a recorded example and reaches no live model or data store.

expinteger

Expiry, seconds since the epoch

surface"web" | "org" | "native" | "mcp" | "sdk"

The surface opening the session: "web" (the consumer site), "org" (an organization workspace), "native" (the mobile app), "mcp" (an MCP server), "sdk" (a program using an API key). Defaults to "sdk".

contextobject
hiddenstring[]

Tools the person chose to hide. A hide list only: it never shows a tool the grant does not hold.

expiresAtstring (date-time)

The grant's expiry as ISO 8601

socketstring

The agent socket path to open with ?grant={token}, on the same host as this API

linksobject

self: this operation. threads: the session's threads, when it has a history.

Example response

7 keys
"response": {
"token": "eyJ2IjoyLCJpYXQiOjE3OTE2OTEwNDQsImV4cCI6MTc5MTY5MTE2NCwiZ3JhbnQiOnsic3ViIjoiV3E4blZ0M2tYeTJMbVI1cFpzN2NKZDRmIiwia2luZCI6ImtleSIsInNjb3BlcyI6WyJjb25zdW1lciJdLCJjcmVkaXQiOnsiY2hhbm5lbCI6ImtleSIsInJlZiI6Ikt4NG1QcTdyVHoyV3ZOOGJMZDVzSGozYyJ9LCJtb2RlbCI6ImRlZmF1bHQifSwic3VyZmFjZSI6InNkayIsImNvbnRleHQiOnsiaGlkZGVuIjpbXX19.gS-jnVeJmZ9uooVu1Ok_0Q8VNHbg-PsxgK3KjkCbPC8",
"grant": {
"sub": "Wq8nVt3kXy2LmR5pZs7cJd4f",
"kind": "key",
"scopes": [1 item],
"credit": {2 items},
"model": "default",
"exp": 1791691164
},
"surface": "sdk",
"context": {
"hidden": [0 items]
},
"expiresAt": "2026-10-11T03:59:24.000Z",
"socket": "/agents/cardog-agent/Wq8nVt3kXy2LmR5pZs7cJd4f",
"links": {
"self": "/v2/agent/session",
"threads": "/v2/agent/threads"
}
}

Errors400401403429500503every non-2xx body is the error envelope

GET/v2/agent/threadssince 2026-10-27

List agent threads

The threads (conversations) on the agent instance a grant names, newest activity first. Costs 0 credits. Without a grant this is your own personal history. To read an organization workspace's history, send the session token from POST /v2/agent/session in the X-Cardog-Agent-Grant header; the grant must be your own, or the read is 401. An anonymous session has no thread history (403), and neither does an organization key or a server token.

Query parameters

qstringoptional

Keep only threads whose name or newest message contains this text (case-insensitive)

Header parameters

X-Cardog-Agent-Grantstringoptional

A session token from POST /v2/agent/session, minted for you. Omit it to read your personal threads.

curl "https://api.cardog.app/v2/agent/threads" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26"

Response

200AgentThreadList
dataobject[]

Newest activity first

idstring

The thread id

namestring | null

The name the agent gave the thread, or null until it has one

lastMessagestring | null

A preview of the newest message, or null

createdAtstring (date-time)

When the thread was opened, ISO 8601

updatedAtstring (date-time)

When the thread last changed, ISO 8601

lastMessageAtstring | null

When the newest message landed, ISO 8601, or null

linksobject

messages: this thread's messages.

linksobject

self: this operation.

Example response

2 keys
"response": {
"data": [
0: {7 items}
],
"links": {
"self": "/v2/agent/threads"
}
}

Errors400401403429500503every non-2xx body is the error envelope

GET/v2/agent/threads/{id}/messagessince 2026-10-27

Read an agent thread

One thread and its stored messages, oldest first, as AI SDK UIMessages. Costs 0 credits. The grant rules are those of GET /v2/agent/threads: your personal history without a grant, the grant's instance with one. A thread id that is not on that instance is a 404.

Path parameters

idstringrequired

Thread id from GET /v2/agent/threads, e.g. "3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f"

Header parameters

X-Cardog-Agent-Grantstringoptional

A session token from POST /v2/agent/session, minted for you. Omit it to read your personal threads.

curl "https://api.cardog.app/v2/agent/threads/3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f/messages" \
  -H "x-api-key: $CARDOG_API_KEY" \
  -H "Cardog-Version: 2026-10-26"

Response

200AgentThreadMessages
threadobject
idstring

The thread id

namestring | null

The name the agent gave the thread, or null until it has one

lastMessagestring | null

A preview of the newest message, or null

createdAtstring (date-time)

When the thread was opened, ISO 8601

updatedAtstring (date-time)

When the thread last changed, ISO 8601

lastMessageAtstring | null

When the newest message landed, ISO 8601, or null

linksobject

messages: this thread's messages.

dataobject[]

Oldest first

idstring
role"system" | "user" | "assistant"
partsobject[]

The message parts, in order

metadataobjectoptional
linksobject

self: this operation. threads: the thread list.

Example response

3 keys
"response": {
"thread": {
"id": "3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f",
"name": "Recalls on a 2021 RAV4",
"lastMessage": "There is one open recall for that model year.",
"createdAt": "2026-10-09T14:02:11.000Z",
"updatedAt": "2026-10-09T14:03:40.000Z",
"lastMessageAt": "2026-10-09T14:03:40.000Z",
"links": {1 item}
},
"data": [
0: {4 items},
1: {4 items}
],
"links": {
"self": "/v2/agent/threads/3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f/messages",
"threads": "/v2/agent/threads"
}
}

Errors400401403404429500503every non-2xx body is the error envelope

Generated from the contract. Machine-readable spec: GET https://api.cardog.app/v2/openapi.json · markdown twin: /docs/reference/agent.md