---
title: "Create a new Cortex Agent Thread and index it."
method: POST
path: "/v1/agent/threads"
tags: ["agent"]
---

# Create a new Cortex Agent Thread and index it.

`POST /v1/agent/threads`

## Request

- Base URL: `http://localhost:8080`
- URL: `http://localhost:8080/v1/agent/threads`
- Auth: one of:
  - API key in cookie `dvt_session`
  - HTTP bearer

Mints a new Snowflake Cortex Agent Thread (an engine call authenticated per `DVT_AGENT_IDENTITY` — the caller's own registered PAT by default, or, in snowflake mode with `DVT_AGENT_IDENTITY=caller`, the caller's own combined Snowflake ingress token, no stored credential — DVT-3961, ADR-0082 Option A) and indexes it in dvt's own thread sidebar — dvt stores the thread id and title only, never the transcript (ADR-0082 D6 no-chat-content); the conversation itself lives entirely in Snowflake.

## Request body

- object
  - `agentFqn` string, required: database.schema.agent — must be on the deployment's v1 agent allowlist (engine-enforced).

## Response `201`

Created.

- object
  - `data` AgentThread: One row of dvt's `agent_threads` sidebar index (DVT-3518, ADR-0082 D6) — an INDEX of a Snowflake Cortex Agent Thread, never the transcript itself. The conversation lives only in Snowflake, addressed by `threadId`.
    - `id` string, uuid, required: dvt's own row id.
    - `threadId` string, required: The opaque Snowflake thread id.
    - `agentFqn` string, required
    - `title` string, nullable: User prose; never mirrored, never derived from transcript content dvt doesn't hold.
    - `lastUsedAt` string, date-time, required
    - `lastErrorAt` string, date-time: Set when the last run against this thread failed upstream with a 404 (an EXPECTED steady state, migration 0099's header) — the thread stays listed, now visibly marked errored, rather than disappearing. NOT a diagnosis of what's actually gone: a 404 here is byte-identical whether the Snowflake-side thread no longer exists or the run targeted a non-existent/mistyped agent FQN (thread creation never validates the FQN). Cleared on the next successful run (self-heal). Absent for a thread with no such error.
    - `createdAt` string, date-time, required
  - `meta` Meta: Response metadata.
    - `requestId` string, required: Correlates with the X-Request-Id header.
    - `total` integer: Item count, present on collection responses.
    - `nextCursor` string, nullable: Opaque keyset-pagination cursor, present on paginated responses (e.g. GET /v1/dashboards) when more rows exist beyond this page. Pass it back as the `cursor` query param to fetch the next page; absent or null on the last page.
    - `roleResolveDegraded` boolean: Snowflake mode only (DVT-2260), on GET /v1/dashboards: present and true when the caller's live Snowflake role resolution failed or was unavailable — role-shared dashboards may be missing from this page. Omitted (not merely false) whenever resolution succeeded or the role-share arm does not apply (off snowflake mode, an org admin/owner, or off the ingress listener).

## Other responses

- `400`: Malformed request.
- `401`: Distinguished by the Problem `type` (DVT-3518/DVT-3961, ADR-0082): - `https://docs.dvt.dev/errors/unauthorized` — missing, invalid, or expired session, same as every other route's `Unauthorized` response. - `https://docs.dvt.dev/errors/agent-caller-token-missing` — snowflake mode, `DVT_AGENT_IDENTITY=caller` only (DVT-3961, ADR-0082 D2d.4): this request carried no ingress caller token for the Cortex Agent call. Reconnect through the Snowflake-ingress-fronted session and retry.
- `403`: Several shapes, distinguished by the Problem `type` (DVT-3518/DVT-3961, ADR-0082): - `https://docs.dvt.dev/errors/agent-consent-required` — no active Snowflake Cortex Agent PAT is registered for the caller, or the stored one has expired or been revoked. Never emitted in snowflake mode under `DVT_AGENT_IDENTITY=caller` — there is no per-user PAT to re-consent for. Register a fresh PAT via `PUT /v1/agent/credential`, then retry. - `https://docs.dvt.dev/errors/agent-caller-not-authorized` — snowflake mode, `DVT_AGENT_IDENTITY=caller` only (DVT-3961, ADR-0082 D2d.4): Snowflake rejected the signed-in user's own combined ingress token for this Cortex Agent. Carries an additive `reason` (`usage_denied` | `token_rejected`) when the engine reported one. Ask a Snowflake administrator to grant USAGE on the agent to your role.
- `502`: The analytics engine could not be reached (`https://docs.dvt.dev/errors/engine-unavailable`) or returned an error (`https://docs.dvt.dev/errors/engine-error`). One 502 on this shape is NOT an engine fault and says so: when Snowflake refuses the caller's-rights LOGIN, the Problem type is `https://docs.dvt.dev/errors/caller-connect-refused` — no session was established and the caller's SQL was never reached, so the remediation is a fresh dvt session rather than the engine logs (DVT-4345).
- `503`: The service or a required dependency is temporarily unavailable.

---

[API](https://skmtc.dev/dvt/apis/dvt-rest-api.md) · [All operations](https://skmtc.dev/dvt/apis/dvt-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dvt/apis/dvt-rest-api/revisions/00016f504165?raw)