POST/v1/threads

Threads

The conversation container an Assistant runs against. A thread holds an ordered message list (cap 5,000); you append messages and create Runs to get assistant replies. Optionally seed it with messages and attach a customer via metadata for spend attribution.

Request

HTTP: POST
URL: /v1/threads
Auth: api_key

Try it

# create a thread, seeded with the first user message
curl https://api.fightclub.pro/v1/threads \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Review PR #42"}],
       "metadata":{"customer_external_id":"u_42"}}'
# => { "id":"thread_...", "object":"thread", ... }

# append another message later
curl https://api.fightclub.pro/v1/threads/thread_abc/messages \
  -H "Authorization: Bearer $FC_API_KEY" -H "Content-Type: application/json" \
  -d '{"role":"user","content":"Also check the tests."}'

Example response

{
  "id": "thread_5Yz8",
  "object": "thread",
  "created_at": 1782300000,
  "metadata": {}
}

A representative 200 body. Ids and timestamps are illustrative.

Body parameters

Name	Type	Default	Description
messages	array	optional	Seed messages: [{ role:"user"\|"assistant", content }].
tool_resources	object	optional	Thread-level tool resources, e.g. { file_search: { vector_store_ids:[...] } }.
metadata	object	optional	Free-form map. Set metadata.customer_id or metadata.customer_external_id to attribute the thread's spend to a customer.

* required.

Response fields

Name	Type	Description
id	string	Thread id (thread_*).
object	string	"thread".
created_at	integer	Unix timestamp.
tool_resources	object	Attached resources.
metadata	object	Your metadata.

Errors

401missing_tokenNo Authorization header was sent.
401invalid_auth_schemeThe scheme was neither Bearer nor Client.
401invalid_token_formatA Bearer token not prefixed ko_.
401invalid_tokenThe API key is unknown, revoked or expired.
403insufficient_scopeThe key is valid but lacks the required scope.
400invalid_messagesA seed message is malformed.
409thread_fullAppending would exceed the 5,000-message cap.
409thread_lockedA run is active on the thread; wait for it to finish before writing.
404not_foundNo such thread or message (also cross-tenant).

See the full error reference.

Related routes

GET	/v1/threads/{thread_id}	Retrieve a thread.
POST	/v1/threads/{thread_id}	Modify thread metadata / tool_resources.
PATCH	/v1/threads/{thread_id}	Alias for modify.
DELETE	/v1/threads/{thread_id}	Delete a thread.
POST	/v1/threads/{thread_id}/messages	Append a message (role + content required).
GET	/v1/threads/{thread_id}/messages	List messages (query: limit, order, after, before, run_id).

Notes

·A thread caps at 5,000 messages; appending past that is 409 thread_full.
·While a run is active the thread is locked: appending a message returns 409 thread_locked.
·Message objects carry id, role, content, attachments, assistant_id, run_id, status and created_at.

Examples

assistants-with-tools →