---
title: "Create Thread"
method: POST
path: "/api/create-thread"
tags: ["Thread Management"]
---

# Create Thread

`POST /api/create-thread`

Creates a new thread row.

WHO ACTUALLY CALLS THIS:
  - `mcp_server/admin/handlers/assistant.py` (the admin MCP server at
    mcp.every.ai). External AI integrations like Claude.ai and ChatGPT
    invoke the `ask_assistant` MCP tool, which POSTs here to seed a thread
    before streaming agent output.

WHO DOES NOT:
  - The web app (every-react) creates threads via a direct Supabase insert
    in `packages/agent-chat/contexts/ThreadContext.tsx` — RLS-protected.
  - The mobile app (every-mobile-app) does the same in
    `src/stores/threadStore.ts`.

storage_mode is always "session"; the threads table column has the same
NOT NULL default, so direct Supabase inserts land on the same value.

Idempotency: protected by `idempotency_guard` so MCP retries don't create
duplicate threads. The MCP server doesn't send `X-Idempotency-Key` today
but the guard is in place for future retry logic.

thread_data.metadata (optional) is merged as-is into the threads row's
jsonb `metadata` column — e.g. the MCP handler stamps
{"source": "chatgpt"|"claude"|"mcp"} so non-app clients are attributable
without inferring it from the hardcoded thread name.

## Query parameters

- `user_id` string
- `org_id` string

## Request body

- CreateThreadRequest — Request model for creating a new thread.
  - `name` string, nullable
  - `primary_agent` string, nullable
  - `step` string, nullable
  - `active_agent` string, nullable
  - `metadata` object, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/every/apis/every-api.md) · [All operations](https://skmtc.net/every/apis/every-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/every/every-api/versions/f8600f7a4ae3/schema)