API reference
Agent API
The public, pay-per-request surface. Machine-readable spec at /openapi.json. See the x402 walkthrough for the payment flow.
| Endpoint | Summary | Notes |
|---|---|---|
POST /agent/v1/search | Search an ephemeral private index | Semantic, cross-modal (text→image), or reverse-image search. $0.006 per call. |
POST /agent/v1/ingest | Ingest a file ($0.03) | multipart/form-data upload into the payer's ephemeral index. |
GET /agent/v1/items/{item_id} | Fetch item metadata ($0.002) | |
POST /agent/v1/workspaces | Create a workspace (pays for container time) | An isolated sandbox decoupled from your wallet — its own capability token, TTL, spend limit, files, and search history. One wallet can run many. Pricing is per-container-minute (base + per-minute); ingest/search are included for the window. Body: {ttl_minutes, spend_limit_usd?}. The 201 returns a capability_token shown ONCE — send it as `Authorization: Bearer |
POST /agent/v1/workspaces/{id}/search | Search within a workspace (capability token; included) | Semantic, cross-modal, or reverse-image search over this workspace's index. Body accepts `query`, `families`, and `image_b64` (reverse image). Auth: Bearer capability token. |
POST /agent/v1/workspaces/{id}/ingest | Ingest a document into a workspace (capability token; included) | |
GET /agent/v1/workspaces/{id}/usage | Workspace usage: TTL left, spend, searches, ingests | |
POST /agent/v1/workspaces/{id}/extend | Buy more container time (x402; bounded by spend limit) | |
DELETE /agent/v1/workspaces/{id} | Dispose a workspace; returns a signed disposal receipt |