REST API overview

The Usable REST API gives scripts and services deterministic access to workspaces, fragments, search, files, collections, and other released platform resources.

Use REST when your application already knows which operation to perform. Use MCP when an AI client should choose tools and sources during a task. Use the dashboard for human-operated workflows.

Base URL and reference

Production requests use:

https://usable.dev/api

The deployed environment exposes two reference surfaces:

• GET https://usable.dev/api/docs — machine-readable OpenAPI document.
• https://usable.dev/docs/api-reference — interactive viewer over that document.

Treat the deployed OpenAPI document as authoritative for exact request fields, response schemas, authentication, and currently available routes. This guide explains stable workflows rather than reproducing every generated schema.

Before you begin

You need:

1. A Usable account.
2. Access to the target workspace.
3. A personal access token with only the required permissions.
4. The relevant workspace and resource IDs.
5. A client that can send HTTPS requests.

Never place real tokens in fragments, source code, shell history, screenshots, or client-side bundles.

Your first request

List accessible workspaces with a bearer token:

curl https://usable.dev/api/workspaces \
  -H "Authorization: Bearer <personal-access-token>" \
  -H "Accept: application/json"

Replace the placeholder at runtime. A successful response proves the token is accepted, but not that it has access to every workspace or operation.

For a workspace-scoped read:

curl "https://usable.dev/api/memory-fragments?workspaceId=<workspace-id>&limit=20&offset=0" \
  -H "Authorization: Bearer <personal-access-token>" \
  -H "Accept: application/json"

Do not assume the list response and a single-resource response use the same envelope. Parse the schema documented for each endpoint.

Content types

Most write endpoints accept JSON:

Content-Type: application/json

File upload uses multipart/form-data. The MCP endpoint uses JSON-RPC 2.0 at /api/mcp; it is not a conventional resource endpoint.

Let your HTTP client construct multipart boundaries. Do not set a hand-written boundary header.

REST, MCP, or dashboard?

Choose REST for:

• imports and exports;
• synchronization jobs;
• deterministic CRUD operations;
• file transfer;
• webhook or token administration;
• service-owned pagination and retry state.

Choose MCP for assistant-led discovery and controlled knowledge maintenance. MCP tool names and arguments do not map one-to-one to REST paths.

Choose the dashboard when a person should review the input, choose a workspace, or confirm a destructive action.

Version and environment drift

The reviewed public reference covers Usable v1.198.1 and OpenAPI version 1.4.0. A target environment can differ during deployment.

Before building or debugging:

1. Fetch /api/docs from the exact environment.
2. Confirm the route, method, security scheme, and schema.
3. Use placeholders in examples.
4. Test with a least-privilege non-production token.
5. Record the platform version from /api/version when reporting a mismatch.

Do not infer support from an MCP tool, old internal guide, or UI button alone.

Safety defaults

• Scope every operation to the intended workspace.
• Validate IDs and user-controlled query values.
• Set request timeouts.
• Retry only safe or idempotent operations.
• Store returned IDs before polling asynchronous work.
• Log request context, not credentials or signed URLs.
• Refetch after create, update, archive, or delete operations.

Related pages

• Authenticate and authorize API requests
• Requests, responses, pagination, and errors
• MCP tools and permissions
• Personal access tokens