API concepts

Space is in development. These guides describe the current development version and the intended workflow. Public sign-ups and hosted agent connections are not available yet.

The rules every route follows: paging, safe retries, revisions, errors, limits and versioning.

Read Build with the API first to create a key and make a request. The API reference lists each route’s fields and errors.

Pagination

List endpoints return next_cursor. To get the next page, pass it back as the after query parameter, or as the after body field for search and export. Repeat until next_cursor is null.

curl -H "Authorization: Bearer $SPACE_API_KEY" \
  "$SPACE_API_URL/v1/spaces/$SPACE_ID/resources?kind=task&after=<next_cursor>"

Search and export are snapshot-consistent. Their first page also returns snapshot; send the same snapshot with after on every following page. If the Space changed in the meantime, the API returns 409 with “Space changed. Restart to include the latest changes.” Start again without after or snapshot.

Safe retries

Writes take a command_id: a UUID your client generates once for each change it intends to make. If a request times out, send it again with the same command_id. The API returns the original result instead of applying the change twice.

Generate a new command_id for every new change. Reusing one for a different request returns 409 with “This command ID was already used for another operation.”

Revisions

Every document, task, memory and item has an integer revision. Create with expected_revision: 0. To update or delete, send the current revision as expected_revision.

If someone changed the item first, the API returns 409. Read the item again, reapply your change to the new revision, and retry.

Errors

Every error body has the same shape, with a message you can show to a person:

{"error": "<human-readable message>"}

• 400The operation is invalid.
• 401The API key is missing, unknown, expired or revoked.
• 402An active subscription is required to add content. Reading, export and deletion still work.
• 403Not allowed: a read-only key, a viewer role, or an operation keys can never do.
• 404Not found. Other Spaces also return 404: a key cannot see them.
• 409Conflict: a stale revision, a reused command ID, or a changed snapshot.
• 413The request body is over 1.5 MB.
• 422One or more fields are invalid.
• 429A Space quota (storage, items or monthly model requests) is exhausted, or the service is busy. Honour Retry-After when it is present.
• 503Temporarily unavailable. Retry with backoff. Also sent, with Retry-After, when the recall or memory-processing queue is full.

Limits

• Request bodies can be up to 1.5 MB.
• Each Space has quotas for storage, items and monthly model requests. See them with GET /v1/spaces/{space_id}/usage.
• Recall and memory processing are queued, with a bounded number running at once. When the queue is full, the API returns 503 with Retry-After.

Stability

The API is versioned under /v1. Within v1 we may add endpoints, optional request fields and new response fields, so ignore fields your client does not recognise. Removing or renaming fields, or changing what they mean, would only happen in a new version.