Skip to main content
POST
Observe observations and return context plus preferences

Authorizations

Authorization
string
header
required

Your API key, shaped sp_<key_id>_<secret>, sent as Authorization: Bearer sp_.... It identifies your organization, not a person. Your organization owns the agents, holds the credit, and is billed. Every key your organization holds reaches the same things, so you rotate a key by minting the new one, deploying it, and revoking the old one.

Keep the key on your server. A request that carries a Sec-Fetch-Site header is refused with 400, because only a browser sets that header. Priors sends no CORS headers, so a browser blocks the call before it leaves the page. The secret is shown once when the key is minted and is stored only as a hash. A lost secret is replaced, never recovered.

An administrator of your organization mints and revokes keys in the Priors application, under Settings. There is no endpoint for it: a key reaches your whole organization, so issuing one is an act of administration.

Headers

X-SP-End-User
string

Your own identifier for the person this request acts for: an account number, a row id, anything stable on your side. It works only with a partner API key. The value is not stored. Priors hashes it together with your organization id, so two clients that send the same string are still two different people.

With the header, you reach the threads that same person created and no others. A new thread is recorded against that person, and GET /v1/agents/{agent_id} returns that person's conversations only. Without the header, the key acts as the organization and reaches every thread on every agent it owns. Learned memory is shared across the agent either way. Only the thread list narrows.

Sent with anything that is not a partner API key, the header returns 400 instead of being ignored. Sent empty or as whitespace, it also returns 400, and it is never read as absent: absent means the whole organization, which is wider access than you asked for. Surrounding whitespace is removed. The 255-character limit is measured on the value as sent.

Required string length: 1 - 255
Pattern: \S

Path Parameters

agent_id
string
required

Unique managed memory-agent identifier.

Maximum string length: 32
Pattern: ^agent_[0-9A-HJKMNP-TV-Z]{26}$
thread_id
string
required

Unique thread identifier scoped to the agent.

Maximum string length: 33
Pattern: ^thread_[0-9A-HJKMNP-TV-Z]{26}$

Body

application/json

The request body of observe-and-enrich. Your own model writes the answer, so Priors has no answer to learn. To have the answer learned, send it back as an observation.

observations
object[]
required

One or more observations. A single item represents real-time observation; multiple observations represent history or bulk ingestion. Array order is preserved exactly and is the only deterministic way to order a batch.

Required array length: 1 - 100 elements
max_context_chars
integer

A hard cut on the returned text, not an instruction about length. The text is written in full and then trimmed to this many characters, so a value shorter than the text leaves the reader with a sentence that stops mid-word. Omit it for no trimming. Set it only when your own model has a small context window. To get shorter text, send detail: brief.

Required range: 100 <= x <= 100000
request_id
string | null

Optional caller-supplied correlation id attached to this request's records. The server generates one when omitted. It is also how you look up later whether the turn was learned.

Maximum string length: 200
detail
enum<string>
default:standard

How much the agent writes: the length of response_context on observe-and-enrich and observe-and-respond, and of the answer on chat. brief: only the most important facts, in 2 to 4 sentences; use it for short replies such as a chat widget, a notification, or an SMS. standard (the default): the normal length; use it for most questions. detailed: every relevant fact, date, name, number, and direct quote the memories hold, with a list or table when the question asks for one or there are many items; use it for reports, audits, the history of a customer, and "list everything" questions. This is an instruction to the agent, not a cut: the text is never trimmed to fit. For a hard limit on size, use max_context_chars.

Available options:
brief,
standard,
detailed

Response

Retrieved response context and preference block

agent_id
string
required
thread_id
string
required
response_context
string
required

Distilled memory context for the caller's main response model. This is not a generated assistant response.

preference
string | null

Learned user-preference block for this turn. null from observe-and-respond (preferences not requested); "" from observe-and-enrich until preference formulation lands.

in_context_memory_ids
string[]

Answer-to-memory provenance: the memory ids in the answering model's context for this response (union across loops). Empty for non-provenance callers.

used_memory_ids
string[]

The subset of in_context_memory_ids the answering model reported actually using. Empty when none.

in_context_memory_turns
string[]

The source turns the in_context_memory_ids were generated from (each memory's turn_id), deduplicated and sorted. Empty for non-provenance callers.

used_memory_turns
string[]

The source turns of used_memory_ids (each memory's turn_id), deduplicated and sorted. Empty when none.

in_context_source_ids
string[]

Stored upload ids referenced by memories in the answering model's context, deduplicated and sorted. Empty when none.

used_source_ids
string[]

Stored upload ids referenced by memories the answering model reported using, deduplicated and sorted. Empty when none.

learning
object[]

Turns in this thread that were not learned: writing their memory failed after an earlier response was already returned, and no earlier response reported them. Each one is reported at least once. GET .../threads/{thread_id}/learning is the full record. Empty when every turn so far was learned or is still being learned.