# Priors API > Priors gives a product a long-term memory. You create an agent, send it observations, and ask it questions. The agent writes memories from the observations and answers from the memories. Memory belongs to the agent. Threads are conversations under an agent. Learning is asynchronous: an observation is accepted with 202 and is learned a moment later. Every answering call also learns from the message it receives. Base URL: https://app.sapientpriors.com/api. Every id is opaque and prefixed by type (agent_, thread_, obs_, mem_, src_, org_, eu_). An id you cannot reach answers 404, never 403. Every error is {"error", "code", "request_id"}; branch on code. One credential: an API key, sent as `Authorization: Bearer sp__`. It identifies an ORGANIZATION, not a person, and is called from a backend. Keys are minted and revoked by an administrator in the Priors application; there is no endpoint for it. Add `X-SP-End-User: ` to act for one named person: it narrows thread access to the threads that person created, and gives them their own rate-limit window. Omit it and the key is the organization, which reaches every thread it owns and spends from one shared window. Empty or whitespace is a 400, never read as absent. A key on a request carrying Sec-Fetch-Site is a 400; no CORS headers are sent. Boundary model: one agent per customer. The agent is the boundary; the header is not. Memory is shared across an agent, so two people on one agent can be answered from each other's facts. 100 agents per organization. The full machine-readable contract is the OpenAPI document: https://www.sapientpriors.com/docs/openapi.yaml ## Start here - [Start here](https://www.sapientpriors.com/docs/introduction): the three ideas and the order in which to use the API. - [The complete lifecycle](https://www.sapientpriors.com/docs/lifecycle): every endpoint in usage order with request, success, failure, and fix. Images: img_url on observe calls, image_source_ids (max 10) on chat, observe-file takes one file per call, which may itself be an image read as a one-page document. No webhooks; poll status. - [Authentication](https://www.sapientpriors.com/docs/authentication): the key, X-SP-End-User, ownership, and the 400/401/404 rules. - [Errors](https://www.sapientpriors.com/docs/errors): every error code, its cause, and what to do. - [Limits](https://www.sapientpriors.com/docs/limits): rate windows per subject and per organization, 10 MB per file, 2,000 pieces, one ingestion at a time per agent, 10 images and 32 MB per turn, 100 agents and 5 live keys per organization. - [Credits](https://www.sapientpriors.com/docs/credits): 0.01 credits per token, about 1.3 tokens per word, observe and observe-file pay input only, answering calls pay input plus output, 402 payment_required at zero, GET /v1/billing. - [Your data](https://www.sapientpriors.com/docs/data): what is stored (memories, conversation, sources, activity, usage), per-organization isolation, who can read what, what deletion does. - [Integration notes](https://www.sapientpriors.com/docs/integration): retry table per call, ordering, client timeouts, RFC 3339 UTC, 200-message thread window, no sandbox, no SDK, /v1 additive versioning. - [Terminology](https://www.sapientpriors.com/docs/terminology): every term defined once. ## Walkthroughs (end to end, with success and failure at every step) - [1. Your first agent, start to finish](https://www.sapientpriors.com/docs/walkthroughs/first-conversation): create, ready, thread, observe, status, observe-and-respond. - [2. Bring your own model](https://www.sapientpriors.com/docs/walkthroughs/bring-your-own-model): observe-and-enrich into your own prompt. - [3. Teach from a document](https://www.sapientpriors.com/docs/walkthroughs/teach-from-a-document): observe-file, ingestion status, chat with citations. - [4. Build a chat interface](https://www.sapientpriors.com/docs/walkthroughs/build-a-chat-interface): chat/stream events, images, citations. - [5. Call Priors from your own backend](https://www.sapientpriors.com/docs/walkthroughs/call-from-your-backend): one agent per customer, X-SP-End-User, list one person's threads from GET /v1/agents/{agent_id}. ## How Priors works - [Agents](https://www.sapientpriors.com/docs/concepts/agents): create, own, lifecycle (initializing, ready, failed), how memory works. - [Threads](https://www.sapientpriors.com/docs/concepts/threads): one conversation, recent context, not a memory boundary. - [Learning](https://www.sapientpriors.com/docs/concepts/learning): observe, observe-file (documents, images, plain text and Markdown), status polling, cancel. `speaker` names who said an observation; without it tags[0] is read as the speaker, and "user" when there are no tags. Files queue per agent (`queued: true`); `interrupted` resumes by itself; a failed job reports its not-learned pieces in `learning`. - [Answering](https://www.sapientpriors.com/docs/concepts/answering): observe-and-enrich (context for your model), observe-and-respond (finished answer, learned unless learn_reply is false), chat and chat/stream (turn with citations). `detail` (brief, standard, detailed) sets the length by instruction; max_context_chars is a hard cut applied after the text is written. Responses list turns that were not learned in `learning`; GET .../threads/{thread_id}/learning looks one request up. - [Sources](https://www.sapientpriors.com/docs/concepts/sources): documents, images, downloads, citations, upload state on the list, finish-learning for a stopped upload, retry-pictures for unread pictures. ## API reference - [Conventions](https://www.sapientpriors.com/docs/api-reference/overview) - Agents: POST /v1/agents, GET /v1/agents, GET|PATCH|DELETE /v1/agents/{agent_id}, GET /v1/agents/{agent_id}/logs - Threads: POST /v1/agents/{agent_id}/threads, GET|PATCH|DELETE /v1/agents/{agent_id}/threads/{thread_id} - Learning: POST .../threads/{thread_id}/observe, POST .../observe-file, GET .../observe/{observation_id}/status, POST .../observe/{observation_id}/cancel, GET .../threads/{thread_id}/learning - Answering: POST .../observe-and-respond, POST .../observe-and-enrich, POST .../chat, POST .../chat/stream - Sources: PUT .../threads/{thread_id}/sources/images, GET /v1/agents/{agent_id}/sources, GET /v1/agents/{agent_id}/sources/{source_id}, GET .../threads/{thread_id}/sources/{source_id}, POST .../threads/{thread_id}/sources/{source_id}/finish-learning, POST .../threads/{thread_id}/sources/{source_id}/retry-pictures - Your key: GET /v1/session, GET /v1/billing ## Optional - [Full documentation in one file](https://www.sapientpriors.com/docs/llms-full.txt)