## Reference: Agent

Sessions and thread history for the Cardog agent

**Availability: coming soon.** The contract below is frozen. The routes are not mounted yet.

### POST /v2/agent/session

Open an agent session *Since 2026-10-27.*

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"): 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".
- `context`? (object)
  - `context.hidden`? (string[]): Tools the person chose to hide. A hide list only: it never shows a tool the grant does not hold.
- `orgToken`? (string): 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.

**Response 200** `AgentSession`: The signed session and the grant it carries

- `token` (string): 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.
- `grant` (object)
  - `grant.sub` (string): The account the session acts as. Every tool read inside a turn runs as this subject.
  - `grant.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.
  - `grant.class`? (string): The organization's class ("oem", "gov", "dealer", "insurer", "fleet", "internal"), or "technician" for a session at the bench. Present when kind is "org".
  - `grant.role`? (string): The member's role at mint time. Present when kind is "org".
  - `grant.tenantId`? (string): The tenant key, e.g. "oem/example". Present when kind is "org".
  - `grant.orgId`? (string): The organization id. Present when kind is "org".
  - `grant.orgSlug`? (string): The workspace slug in the org surface's URL. Present when kind is "org".
  - `grant.orgName`? (string): The organization's display name. Present when kind is "org".
  - `grant.scopes` (string[]): The tool scopes the session holds, e.g. ["consumer"] or ["org:*", "org:oem"]. A tool outside them is absent, not refused.
  - `grant.credit` (object): The ledger a turn debits
    - `grant.credit.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.
    - `grant.credit.ref` (string): The account on that channel: the user id for a session, the key id for a key, the organization id for an org
  - `grant.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.
  - `grant.exp` (integer): 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".
- `context` (object)
  - `context.hidden` (string[]): Tools the person chose to hide. A hide list only: it never shows a tool the grant does not hold.
- `expiresAt` (string (date-time)): The grant's expiry as ISO 8601
- `socket` (string): The agent socket path to open with `?grant={token}`, on the same host as this API
- `links` (object): `self`: this operation. `threads`: the session's threads, when it has a history.

**Errors** (all use the ErrorEnvelope): 400, 401, 403, 429, 500, 503

**Example: cURL**

```bash
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"}'
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const agentSession = await client.v2.agent.session({ surface: "sdk" });
console.log(agentSession.token);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

agent_session = client.v2.agent.session({"surface": "sdk"})
print(agent_session.token)
```

### GET /v2/agent/threads

List agent threads *Since 2026-10-27.*

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | no | Keep only threads whose name or newest message contains this text (case-insensitive) |

**Header parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Cardog-Agent-Grant` | string | no | A session token from POST /v2/agent/session, minted for you. Omit it to read your personal threads. |

**Response 200** `AgentThreadList`: The threads, newest activity first

- `data` (object[]): Newest activity first
  - `data[].id` (string): The thread id
  - `data[].name` (string | null): The name the agent gave the thread, or null until it has one
  - `data[].lastMessage` (string | null): A preview of the newest message, or null
  - `data[].createdAt` (string (date-time)): When the thread was opened, ISO 8601
  - `data[].updatedAt` (string (date-time)): When the thread last changed, ISO 8601
  - `data[].lastMessageAt` (string | null): When the newest message landed, ISO 8601, or null
  - `data[].links` (object): `messages`: this thread's messages.
- `links` (object): `self`: this operation.

**Errors** (all use the ErrorEnvelope): 400, 401, 403, 429, 500, 503

**Example: cURL**

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

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const agentThreadList = await client.v2.agent.threads();
console.log(agentThreadList.data);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

agent_thread_list = client.v2.agent.threads()
print(agent_thread_list.data)
```

### GET /v2/agent/threads/{id}/messages

Read an agent thread *Since 2026-10-27.*

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Thread id from GET /v2/agent/threads, e.g. "3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f" |

**Header parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `X-Cardog-Agent-Grant` | string | no | A session token from POST /v2/agent/session, minted for you. Omit it to read your personal threads. |

**Response 200** `AgentThreadMessages`: The thread and its messages

- `thread` (object)
  - `thread.id` (string): The thread id
  - `thread.name` (string | null): The name the agent gave the thread, or null until it has one
  - `thread.lastMessage` (string | null): A preview of the newest message, or null
  - `thread.createdAt` (string (date-time)): When the thread was opened, ISO 8601
  - `thread.updatedAt` (string (date-time)): When the thread last changed, ISO 8601
  - `thread.lastMessageAt` (string | null): When the newest message landed, ISO 8601, or null
  - `thread.links` (object): `messages`: this thread's messages.
- `data` (object[]): Oldest first
  - `data[].id` (string)
  - `data[].role` ("system" | "user" | "assistant")
  - `data[].parts` (object[]): The message parts, in order
  - `data[].metadata`? (object)
- `links` (object): `self`: this operation. `threads`: the thread list.

**Errors** (all use the ErrorEnvelope): 400, 401, 403, 404, 429, 500, 503

**Example: cURL**

```bash
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"
```

**Example: TypeScript** (`npm install @cardog/api`)

```typescript
import { CardogClient } from "@cardog/api";

const client = new CardogClient({ apiKey: process.env.CARDOG_API_KEY });

const agentThreadMessages = await client.v2.agent.thread("3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f");
console.log(agentThreadMessages.thread);
```

**Example: Python** (`pip install cardog`)

```python
import os

from cardog import Cardog

client = Cardog(api_key=os.environ["CARDOG_API_KEY"])

agent_thread_messages = client.v2.agent.thread("3f2b9c1e-7a4d-4e8b-9c0f-1a2b3c4d5e6f")
print(agent_thread_messages.thread)
```

---

Previous: [Platform](https://cardog.app/docs/reference/platform.md) (API reference)
Next: [SDKs](https://cardog.app/docs/sdks.md) (SDKs & MCP)