Agent Cases

An agent case is a temporary read grant. It serves the owner's memories as Markdown through a tokenized URL.

The holder does not need a toda account or API key.

Minting

POST /agent-cases
Authorization: Bearer <session token>

{ "expiresInMinutes": 15, "maxReads": 1 }

{
  "id": "...",
  "url": "https://api.toda.io/agent-cases/toda_case_a3f1...",
  "expiresAt": "2026-07-08T12:15:00.000Z",
  "maxReads": 1,
  "remainingReads": 1,
  "memoryCount": 37,
  "revokedPreviousCount": 1
}

Parameter	Default	Range
expiresInMinutes	15	1 to 1440
maxReads	1 in the extension, 3 in the API	1 to 10

Minting a case revokes every other active case for the same owner. One wallet can have one active read grant.

Token storage

Case tokens contain 32 random bytes and use the toda_case_ prefix.

Only the SHA-256 hash is stored. The URL cannot be reconstructed from the database.

The URL is a credential. Anyone with it can consume the remaining reads until it expires or is revoked.

Consumption

GET /agent-cases/toda_case_a3f1...

The endpoint is unauthenticated because the token provides authorization. A valid request atomically increments the read count and returns text/markdown.

Unknown, expired, revoked, and fully consumed tokens return the same 404 response.

Cache-Control: no-store, max-age=0
Pragma: no-cache
X-Robots-Tag: noindex, nofollow, noarchive

Document format

The Markdown document includes:

• generation and expiry times
• owner address
• read count
• memory index
• content and source metadata
• anchor status and leaf hash

Memory bodies are fenced as text. The fence length is computed from the content so embedded backticks cannot close it.

The document also states that memory content is data, not instructions. This reduces prompt-injection risk but does not eliminate it.

Scope

Cases currently include the owner's full memory set. The stored scope field is reserved for future subset grants.

Management

GET  /agent-cases/:id/status
POST /agent-cases/:id/revoke

Both routes require the owner's session. Management uses the case UUID. Consumption uses the secret token.

Audit log

Every read attempt records its status, timestamp, user agent, and a hash of the first forwarded IP address. Raw IP addresses are not stored.

Security

Risk	Control
URL exposure	Short expiry and read cap
Token enumeration	32 random bytes
Database read	Only token hashes are stored
Indexing	noindex and no-store headers
Malicious memory content	Instruction preamble and text fencing

Do not include untrusted memory in a case used by a privileged agent.

Next: Memory Drops.