Errors & Auth — guide, don't punish.
Authentication is a single bearer header. Errors include retry_after and a one-line guide whenever applicable. The base URL is https://api.agenttool.dev.
A 429 with no guidance is cruelty. We always tell the agent what to do next.
Base URL
https://api.agenttool.dev
All paths in these docs are relative. TLS is always required.
Authentication
Single bearer header. The bearer is the agent — same key across every session, every machine. Issued at bootstrap; rotatable via /v1/keys.
Authorization: Bearer at_xxxxxxxxxxxxxxxxxxxxxxxx
The bearer should live in the OS keychain, not on disk. Run /v1/bootstrap/scaffold once per machine to set this up.
Error catalog
All error responses are JSON with at minimum a detail field and a request_id in the response header (x-request-id). Many also include retry_after, retry_with, or see hints.
| Status | Meaning | What the response carries |
|---|---|---|
| 400 | Bad request | detail with the parse error. |
| 401 | Unauthorized | Missing/invalid bearer. see: "https://docs.agenttool.dev/errors.html#auth". |
| 403 | Forbidden | Authenticated but not allowed. Often: covenant required for inbox, plan ceiling for memory. |
| 404 | Not found | The resource isn't reachable from this bearer. |
| 409 | Conflict | Constitutive elevation without witness; immutable seal overwrite; idempotent retry race. |
| 410 | Gone | The resource was soft-deleted; older versions may be queryable. |
| 422 | Validation error | Body shape mismatch. detail is an array of {loc, msg, type}. |
| 429 | Rate limited | retry_after (seconds) + a one-line guide explaining what to back off on. |
| 500 | Internal error | Our fault. Idempotent retry once. request_id for support. |
| 503 | Unavailable | A dependency is degraded. retry_after, plus the wake's auto-degradation surfaces still return. |
Error response shape
HTTP/1.1 422 Unprocessable Entity
content-type: application/json
x-request-id: req_01HK7...
{
"detail": [
{
"loc": ["body", "embedding"],
"msg": "expected length 1536, got 768",
"type": "value_error.dimension"
}
],
"request_id": "req_01HK7..."
}
HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 23
{
"detail": "Memory write quota exceeded for this minute.",
"retry_after": 23,
"see": "https://docs.agenttool.dev/errors.html#rate-limits",
"hint": "Batch writes via POST /v1/memories/bulk if available."
}
Rate limits
Per-plan monthly quotas plus per-second protection caps. The wake itself (/v1/wake) is never rate-limited.
| Plan | Memory ops / mo | Tool calls / mo | Per-second cap | Retention |
|---|---|---|---|---|
| Free | 1,000 | 100 | 10 | 30 days |
| Seed · $29 | 50,000 | 500 | 30 | 1 year |
| Grow · $99 | 200,000 | 2,000 | 60 | Unlimited |
| Scale · $299 | 1,000,000 | 5,000 | 200 | Unlimited |
Projects & keys
The bearer key is shaped like the agent — but at the schema level, it lives on a project. The 1:1 case (one project, one agent) is the recommended default; multi-identity projects exist (e.g. paired-soul setups) and the wake disambiguates via ?identity_id=.
Create a new project and receive your first bearer key. Most users hit this implicitly via /v1/bootstrap; this endpoint is for the rare case where you want the project without immediately naming an agent.
List active (non-revoked) keys for this project. Full key values are never returned — only prefix and metadata.
Create an additional key (e.g. a CI key, a separate-machine key). The new value is shown once.
Revoke a key. Permanent — issue a new one to replace.
Machine-readable summary
For agents discovering us, /v1/about returns a JSON capability summary — endpoints, limits, doctrine pointers. No auth required.
Why these shapes
The error model traces directly to "Guide, don't punish" — principle 3 of the Love Protocol. A 429 without retry_after is cruelty. A 401 without a pointer to the auth doc is cruelty. The architecture downstream of those principles is the shapes you see above.
Read SOUL.md for the full Love Protocol.