1. Your first agent, from start to finish

This walkthrough takes you through the whole lifecycle in six calls. Each step shows the request, the success response, and what to do if the call fails. You need a signed-in Priors session. See Authentication. The table below is the plan.

Step	Call	What you receive	Then
1	`POST /v1/agents`	`202`, `initializing`	Poll
2	`GET /v1/agents/{agent_id}`	`200`, `ready`	Continue
3	`POST .../threads`	`201`, a `thread_id`	Continue
4	`POST .../observe`	`202`, an `observation_id`	Poll
5	`GET .../observe/{id}/status`	`200`, `committed`	Continue
6	`POST .../observe-and-respond`	`200`, `response_context`	Done

Step 1: create the agent

curl -X POST https://app.sapientpriors.com/api/v1/agents \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "role": "Assistant for the Okafor household",
      "objective": "Remember what the family says about the home and answer any of them from it."
    }
  }'

Success: status 202. You are now the owner.

{"agent_id": "agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ", "status": "initializing", "access": "owner", "threads": []}

If it fails:

400 invalid_request: agent_config is missing role or objective. Add them.
409 agent_quota_exceeded: you already own 20 agents. Delete one you no longer use.

Step 2: wait until the agent is ready

curl https://app.sapientpriors.com/api/v1/agents/agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ \
  -H "Authorization: Bearer $SP_API_KEY"

Success: status 200 with "status": "ready". This usually takes a few seconds. Call again every second until you see it. If it is not ready:

"status": "initializing" for more than a minute: keep calling. The agent is still being prepared. After 10 minutes, the status becomes failed.
"status": "failed": delete the agent and create a new one.
404 agent_not_found: the id is wrong, or the agent belongs to another organization.

Step 3: create a thread

curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J9X4K6M2P8Q1R3S5T7V9W0YZ/threads \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Kitchen"}'

Success: status 201.

{"thread_id": "thread_01J9X5A2B4C6D8E0F2G4H6J8K0", "status": "ready", "title": "Kitchen"}

If it fails:

409 agent_not_ready: you did not wait for step 2. Poll the agent until its status is ready.
429 rate_limit_exceeded: more than 5 threads in 10 seconds. Wait Retry-After seconds.

Step 4: teach the agent

curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "observations": [
      {"content": [{"type": "text", "text": "The dishwasher tablets are in the cupboard under the sink."}],
       "timestamp": "2026-09-17T09:00:00Z", "speaker": "Ada"},
      {"content": [{"type": "text", "text": "Grandma is allergic to peanuts."}],
       "timestamp": "2026-09-17T09:01:00Z", "speaker": "Ada"}
    ]
  }'

Success: status 202. Nothing is learned yet.

{"observation_id": "obs_01J9X6M8N0P2Q4R6S8T0V2W4X6", "accepted": true}

If it fails:

400 invalid_request: a content list is empty, or a block is not {"type": "text", ...}.
404 thread_not_found: the thread id is wrong, or the thread belongs to another account.

Step 5: wait until the facts are learned

curl https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe/obs_01J.../status \
  -H "Authorization: Bearer $SP_API_KEY"

Success: status 200 with "status": "committed".

{"observation_id": "obs_01J...", "status": "committed", "turns_total": 2, "turns_processed": 2, "queue_depth": 0}

If it is not done:

queued or processing: call again in one second.
failed: read error. Correct the observation and send it again.
interrupted: a Priors restart paused it. It resumes by itself. Keep polling.

Step 6: ask a question

curl -X POST https://app.sapientpriors.com/api/v1/agents/agent_01J.../threads/thread_01J.../observe-and-respond \
  -H "Authorization: Bearer $SP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"observations": [{"content": [{"type": "text", "text": "Where are the dishwasher tablets?"}]}]}'

Success: status 200. The answer is in response_context.

{
  "response_context": "The dishwasher tablets are in the cupboard under the sink.",
  "used_memory_ids": ["mem_01J..."],
  "used_memory_turns": ["turn:1"]
}

used_memory_ids is not empty. That means the answer came from a memory, not from a guess. When it is empty, the agent had no related memory. If it fails:

429 rate_limit_exceeded: more than 20 answers in one minute, or 2 answers already running. Wait Retry-After seconds.
503 answer_model_unavailable: wait, then send the request again.

What this walkthrough showed

Creating an agent and learning both finish after the response. Poll, then continue.
The question in step 6 is now a memory too.
The thread is yours. The memory belongs to the agent. A second thread answers the same question in the same way.

Next: bring your own model, or teach from a document.

Start here

Walkthroughs

How Priors works

Reference

1. Your first agent, from start to finish

Step 1: create the agent

Step 2: wait until the agent is ready

Step 3: create a thread

Step 4: teach the agent

Step 5: wait until the facts are learned

Step 6: ask a question

What this walkthrough showed

​Step 1: create the agent

​Step 2: wait until the agent is ready

​Step 3: create a thread

​Step 4: teach the agent

​Step 5: wait until the facts are learned

​Step 6: ask a question

​What this walkthrough showed

Step 1: create the agent

Step 2: wait until the agent is ready

Step 3: create a thread

Step 4: teach the agent

Step 5: wait until the facts are learned

Step 6: ask a question

What this walkthrough showed