curl --request POST \
--url https://app.sapientpriors.com/api/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
}
}
'import requests
url = "https://app.sapientpriors.com/api/v1/agents"
payload = { "agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_config: {
role: 'Household finance assistant',
objective: 'Answer questions about this household of accounts, payments and statements.'
}
})
};
fetch('https://app.sapientpriors.com/api/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent_id": "agent_01JZ8X9K6AS3V8SGP0Q9A2P4FH",
"status": "initializing",
"agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
},
"created_at": "2026-07-16T12:00:00Z",
"updated_at": "2026-07-16T12:00:00Z",
"expires_at": null
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}Create a memory agent
Creates a managed memory agent. The returned agent_id owns a global memory index. Create a separate agent when complete memory isolation is required.
curl --request POST \
--url https://app.sapientpriors.com/api/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
}
}
'import requests
url = "https://app.sapientpriors.com/api/v1/agents"
payload = { "agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
} }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_config: {
role: 'Household finance assistant',
objective: 'Answer questions about this household of accounts, payments and statements.'
}
})
};
fetch('https://app.sapientpriors.com/api/v1/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"agent_id": "agent_01JZ8X9K6AS3V8SGP0Q9A2P4FH",
"status": "initializing",
"agent_config": {
"role": "Household finance assistant",
"objective": "Answer questions about this household of accounts, payments and statements."
},
"created_at": "2026-07-16T12:00:00Z",
"updated_at": "2026-07-16T12:00:00Z",
"expires_at": null
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}{
"error": "<string>",
"code": "<string>",
"request_id": "<string>",
"details": "<string>"
}Authorizations
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.
Body
Show child attributes
Show child attributes
Reserved for a future idle-expiry policy. Stored and returned, but agents do not expire today. Capped at 2592000 (30 days).
0 <= x <= 2592000The surface an agent sits on. external is the only one an API key reaches, and the only one it can create, so you can leave this field out and receive it. The agent belongs to your organization rather than to any person, and it appears in no directory.
external Response
Agent reserved; dependency initialization continues asynchronously
Unique identifier for the managed memory agent.
^agent_[0-9A-HJKMNP-TV-Z]{26}$initializing, ready, failed, deleting, deleted Your relationship to the agent. An agent your key created is always owner.
owner Show child attributes
Show child attributes
Always null today: agents do not expire on their own.
How many turns were already learned into the memory index this agent restored from. It is 0 for a new agent. You cannot work this out yourself, because the index is on our side. A client that resumes a backfill reads it to know how many observations to skip.
x >= 0The surface an agent sits on. external is the only one an API key reaches, and the only one it can create, so you can leave this field out and receive it. The agent belongs to your organization rather than to any person, and it appears in no directory.
external The threads on this agent that the caller reaches, newest first. With X-SP-End-User, that is the threads that person created and no others, which is how you list one person's conversations. Without the header your key is the organization, so it is every thread on the agent.
Show child attributes
Show child attributes