API resource directory and OpenAPI

Use this page to find a resource family, then inspect the deployed OpenAPI document for exact methods, fields, security, and response shapes.

• Machine-readable: GET https://usable.dev/api/docs
• Interactive: https://usable.dev/docs/api-reference

The reviewed public reference covers Usable v1.198.1 and OpenAPI version 1.4.0. Runtime availability is determined by the target environment.

Inspect an endpoint

1. Open the interactive reference or fetch /api/docs.
2. Find the route and HTTP method.
3. Check its security requirement.
4. Inspect path, query, and body schemas.
5. Review success and error responses.
6. copy the shape using placeholders only.
7. Test with a least-privilege credential in a safe workspace.
8. Confirm the actual response before generating a production client.

Do not infer one route's envelope, pagination, or array encoding from another.

Resource families

Authentication and tokens

Session helpers live under /api/auth/*; PAT management is under /api/tokens. External services normally use bearer PATs, while some dashboard routes require browser sessions.

See Authenticate and authorize API requests.

Workspaces and collaboration

/api/workspaces covers lifecycle, accessible/public discovery, subscriptions, settings, members, invitations, fragment types, and selected workspace automation routes.

See Workspaces and collaboration API.

Fragments and search

/api/memory-fragments, /api/fragments/*, and /api/search* cover deterministic CRUD, exact listing, structured search, agentic discovery, saved searches, and related analytics where released.

See Fragments and search API.

Files and attachments

Released routes include:

POST   /api/files/upload
GET    /api/files/search
GET    /api/files/{id}
PATCH  /api/files/{id}
DELETE /api/files/{id}
GET    /api/files/{id}/download
GET    /api/files/{id}/status
POST   /api/files/{id}/cancel
POST   /api/files/bulk-delete
POST   /api/files/{id}/attachments
DELETE /api/files/{id}/attachments
GET    /api/fragments/{id}/files

See Integrate file workflows for safe upload, polling, attachment, and download behavior.

Collections

Collection lifecycle and membership routes live under /api/workspaces/{id}/collections. Batch fragment-to-collection lookup is exposed under the documented workspace fragment-collections route.

See Collections.

Webhooks

Workspace webhook list/create/read/update/delete and test-trigger routes live under /api/workspaces/{id}/webhooks. Use HTTPS receivers, verify released authentication/signing behavior, rotate secrets, and make consumers idempotent.

A dedicated Webhooks & automation section will cover the operational contract in more depth.

Applications

Released application record routes include list, create, read, and update operations under /api/applications. Availability and configuration can depend on the account and application flow.

A dedicated Applications & integrations section will cover supported grants and lifecycle guidance.

Graph and AI helpers

Graph routes under /api/graph support workspace graph retrieval, statistics, and exploration. AI helper routes under /api/ai expose released embedding, summary, tag, availability, and usage operations.

AI helpers can be tier-, provider-, usage-, or environment-dependent. Supply deterministic metadata for imports that must not depend on model output.

Profile, notifications, and subscription

Released families include profile/user helpers, notifications, subscription state, tiers, tier changes, payment confirmation, and invoices. Some routes are dashboard-, organization-, or admin-specific.

A dedicated Billing, plans & usage section will document safe user and administrator workflows.

MCP

GET /api/mcp describes the MCP server and POST /api/mcp carries JSON-RPC 2.0. HTTP 200 does not prove a tool succeeded; inspect the JSON-RPC result and isError.

See MCP tools and permissions.

Health, version, and docs

GET /api/health
GET /api/version
GET /api/docs

Use version information when reporting a discrepancy between documentation and runtime behavior.

Hosted Zone routing

Usable v1.198.1 adds Hosted Zone management and optional Leaf placement. Existing Cloud data-plane routes can reject a Leaf-backed workspace with a typed response such as:

{
  "code": "HOSTED_ZONE_REQUIRED",
  "error": "HOSTED_ZONE_REQUIRED",
  "hostedZoneId": "<hosted-zone-id>",
  "endpointUrl": "https://leaf.example.com"
}

Treat this as a boundary instruction:

1. Verify the caller may access the workspace.
2. Obtain the released browser or service token handoff appropriate to the route.
3. Send private data-plane calls to the authorized Leaf endpoint.
4. Never silently resend private payloads to Cloud.
5. Handle unsupported Hosted Zone V1 operations explicitly.

File operations remain unsupported for Hosted Zone V1. Use a Cloud workspace for file workflows until a released Leaf file surface exists.

What not to assume

• An endpoint exists because a dashboard control exists.
• An MCP tool maps to a same-named REST route.
• Every route accepts bearer PATs.
• Every list has the same pagination fields.
• Every successful write is immediately indexed.
• Every environment is on the reviewed release.
• Old internal rate-limit values apply globally.

Report a contract mismatch

Capture:

• target origin and /api/version response;
• method and route template;
• OpenAPI operation and expected schema;
• actual status and redacted body;
• non-sensitive workspace/resource context;
• timestamp and repeatability.

Do not include credentials, cookies, private content, file bytes, or signed URLs.

Related pages

• REST API overview
• Requests, responses, pagination, and errors
• MCP tools and permissions
• Integrate file workflows