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

# Conventions

> The base URL, the format of ids, how to read long lists, which calls finish later, and the format of errors.

This page lists the rules that every endpoint follows. Each endpoint page has the same layout: the parameters, the request body, every response, and an example in curl, Python, and JavaScript.

Every endpoint on these pages takes your API key, and every one that acts inside a thread also takes `X-SP-End-User`. See [Authentication](/docs/authentication).

## Base URL

Every path on these pages is relative to:

```
https://app.sapientpriors.com/api
```

Every request body and response body is JSON, except file uploads and downloads.

## Ids

Every id is a string that Priors creates. The first part tells you the type.

| Prefix | Type |
| - | - |
| `agent_` | Agent |
| `thread_` | Thread |
| `obs_` | Observation request |
| `mem_` | Memory |
| `src_` | Source |
| `org_` | Your organization, which is what a key with no `X-SP-End-User` acts as |
| `eu_` | One of your customers, derived from the `X-SP-End-User` value you sent |
| `sp_` | An API key. The part after the prefix is the key id, and the part after that is the secret. |

An id your key cannot open returns `404`, never `403`, so a key cannot be used to learn which ids exist.

## Long lists

List calls that can return many items accept `limit` and `cursor`. The response has `next_cursor`. Send it back as `cursor` to receive the next page. When `next_cursor` is missing or `null`, you have the last page.

## Calls that finish later

`POST /v1/agents`, `DELETE /v1/agents/{agent_id}`, `DELETE .../threads/{thread_id}`, `observe`, and `observe-file` return `202`. The work continues after the response. To know when it is done, poll the resource or the observation status.

## Errors

Every error has the format `{"error": "...", "code": "...", "request_id": "..."}`. See [Errors](/docs/errors) for every code.

## Rate limits

A `429` response has `Retry-After` in seconds and `X-RateLimit-Reset` as a Unix timestamp. Wait, then send the request again.


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