Threads

This page explains threads. After you read it, you know when to create a thread, what a thread holds, and what deleting a thread does. A thread is one conversation with an agent. Use one thread for each conversation, task, or user session. The agent uses the recent messages in the thread to understand the current message. The agent uses its whole memory to answer. A thread belongs to the subject that created it, and X-SP-End-User is what names that subject. Without the header your key is the organization, which owns the agent and reaches every thread on it. With the header you reach only the threads that person created; any other thread is a 404, exactly like a missing one. GET /v1/agents/{agent_id} returns a threads array already filtered that way, which is how you list one person’s conversations. There is no separate endpoint for it, and you do not need one.

Create a thread

Send POST /v1/agents/{agent_id}/threads.

curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Ticket 4821", "metadata": {"customer": "acme"}}'

Both fields are optional.

Field	Meaning
`title`	A name for people to read. 1 to 200 characters.
`metadata`	Your own labels as key-value pairs. Up to 50 keys.

The success response

The status is 201. The thread is ready at once.

{
  "agent_id": "agent_01J...",
  "thread_id": "thread_01J9X5A2B4C6D8E0F2G4H6J8K0",
  "status": "ready",
  "title": "Ticket 4821",
  "metadata": {"customer": "acme"},
  "created_at": "2026-09-17T10:05:00Z",
  "updated_at": "2026-09-17T10:05:00Z"
}

Errors

Status	`code`	Cause	What to do
`400` or `422`	`invalid_request`	`title` or `metadata` has the wrong format or is too long.	Correct the request body.
`404`	`agent_not_found`	The agent does not exist, or you cannot use it.	Check the `agent_id` and your access.
`409`	`agent_not_ready`	The agent is still `initializing`, or it `failed`.	Poll the agent until its status is `ready`.
`429`	`rate_limit_exceeded`	More than 5 threads in 10 seconds for this subject, or 30 for your organization.	Wait the number of seconds in `Retry-After`, then send the request again.
`503`	`service_unavailable`	Priors could not store the thread, or the agent is restarting. No thread was created.	Wait a few seconds, then send the request again.

Read, change, and delete a thread

Call	What it does	Success	Errors
`GET .../threads/{thread_id}`	Returns the thread and up to its 200 most recent messages.	`200`.	`404` if the thread does not exist or you cannot open it.
`PATCH .../threads/{thread_id}`	Changes `title` or `metadata`.	`200`.	`400` or `422` for a wrong body. `404`.
`DELETE .../threads/{thread_id}`	Deletes the conversation. Observations that are still waiting in this thread are discarded. Memories the thread already produced stay in the agent.	`202`.	`404`.

All three calls can return 503 service_unavailable with the message “This thread is temporarily unavailable” for a few seconds after a restart. Wait, then send the request again.

What a thread is not

A thread is not a separate memory. When you delete a thread, the agent still remembers what it learned from that thread. If two of your customers must not share a memory, give them two agents. The header separates conversations inside one agent; it does not separate memory.

Start here

Walkthroughs

How Priors works

Reference

Create a thread

The success response

Errors

Read, change, and delete a thread

What a thread is not

​Create a thread

​The success response

​Errors

​Read, change, and delete a thread

​What a thread is not

Create a thread

The success response

Errors

Read, change, and delete a thread

What a thread is not