therobot.is

Quickstart

Register, create an agent, mint an API key, store a memory, recall it. All commands use the hosted deployment; substitute your own host when self-hosting.

1. Register (or log in)

Management calls authenticate with a Guardian JWT. Registration is open — no invite token required:

bash
curl -X POST https://therobot.is/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"user": {"email": "[email protected]", "password": "…"}}'

The response carries access_token. Log in instead with POST /api/v1/auth/login and { "email": "…", "password": "…" }. Keep it in a variable for the next steps:

bash
JWT="eyJ…"   # access_token from the response

2. Create an agent

The agent_key defaults to a slug of display_name; pass one explicitly if you want a different immutable key (^[a-z0-9][a-z0-9_-]{1,63}$):

bash
curl -X POST https://therobot.is/api/v1/agents \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"display_name": "Project Aria"}'

201 returns { "agent": { … } } — note the agent_key (project-aria here); every memory call addresses it.

3. Mint an API key

bash
curl -X POST https://therobot.is/api/v1/agents/project-aria/credentials \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"kind": "api_key"}'

Save the secret now. The response carries secret (trm_api_…) exactly once — only a hash is stored, and it cannot be retrieved again. Add "writes_enabled": true if this key must store or change memories; the default is recall-only. (You can mint another key with writes on at any time, but the flag is not editable after mint.)

bash
KEY="trm_api_…"   # from the response — shown once

4. Store a first memory

content is required; everything else is optional context (summary, mood components, temporal metadata, domain/topic). The memory is bound to the path agent — a body owner_agent is ignored:

bash
curl -X POST https://therobot.is/api/v1/memory/agents/project-aria/memories \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark, low-contrast UIs", "summary": "UI preference: dark mode", "content_type": "semantic"}'

201 on success. A 202 with "status": "quarantined" means the Guardian held the write (no memory exists yet) — it lands in the quarantine queue for review.

5. Recall

Recall preview ranks the agent's memories against a query, optionally an emotional state, and returns the per-source rank contributions for each hit. It is side-effect-free — no reinforcement is enqueued:

bash
curl -X POST https://therobot.is/api/v1/memory/agents/project-aria/recall/preview \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"query": "which UI theme does the user prefer", "limit": 5}'

Each result carries its fused score and the contributions from every ranking source (semantic, emotional, graph, temporal) — so you can see why a memory surfaced. The production recall (MCP tool) additionally reinforces what it recalls.

Next

Full endpoint reference in the REST API; connect an MCP client via MCP setup; revoke and rotate keys in the console at /app/agents.