Create a Thread for an Agent API Endpoint
Creates a durable Thread from the latest saved private Agent. Publishing and userId are not required. Input and files are optional.
/agents/{agentId}/threadsCreates a durable Thread from the latest saved private Agent. Publishing and userId are not required. Input and files are optional. The admitted configuration is frozen for this Thread; subsequent Agent edits affect only new Threads.
Authorization
publicApiBearer Use Authorization: Bearer msp_... . Project API keys can configure Agents, execute Sessions, and access files only in their Project. Key and account management require console or CLI login. Legacy account tokens are rejected.
In: header
Path Parameters
Agent API Endpoint ID from the Agent's API Access panel. v1 IDs are bare ULIDs.
^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$ulidHeader Parameters
Optional key for retry-safe create-thread and send-events calls. Reusing the same key with the same request returns the original response. Reusing the key while the original request is still processing returns 409.
length <= 128Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Create a durable Thread from the latest saved private Agent configuration. userId is optional; omit input for an idle Thread. Existing Threads retain their admitted configuration.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/agents/01J00000000000000000000001/threads" \ -H "Idempotency-Key: thread-20260528-linear-eng-123" \ -H "Content-Type: application/json" \ -d '{}'{ "links": { "thread": "string" }, "run": { "completedAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z", "error": { "code": "string", "message": "string", "retryable": true }, "finalOutput": { "text": "string", "warnings": [ { "code": "unresolved_provider_citation", "count": 1 } ] }, "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "startedAt": "2019-08-24T14:15:22Z", "status": "queued", "trigger": "user_prompt", "updatedAt": "2019-08-24T14:15:22Z" }, "thread": { "agent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "created_at": "2019-08-24T14:15:22Z", "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "last_run_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "source": "api", "status": "IDLE", "title": "string", "updated_at": "2019-08-24T14:15:22Z", "userId": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}{ "error": { "code": "agent_not_published", "message": "string" }}