> ## Documentation Index
> Fetch the complete documentation index at: https://www.sapientpriors.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Threads

> A thread is one conversation with an agent. How to create, read, change, and delete one.

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`.

```bash theme={null}
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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.