REST API reference

The Workspace exposes its capabilities over a REST API rooted at your workspace URL. Most enterprise integrations will use only a small slice of this surface — the custom endpoints you write and a handful of admin/auth endpoints.

This page describes the contract for the built-in endpoints. For your own endpoints, see Custom Endpoints.

Base URL

https://<your-workspace-host>/api/

For local development that is typically http://localhost:8080/api/.

Authentication

All authenticated endpoints accept a bearer token:

Authorization: Bearer <token>

See Token scopes for the three token types (session JWT, API token, endpoint token) and how to choose between them.

Unauthenticated endpoints — at the moment, only the login routes — accept and return JSON without an Authorization header.

Content type

Request and response bodies are JSON unless explicitly noted. Use:

Content-Type: application/json
Accept: application/json

Standard response envelopes

Successful responses are bare JSON values shaped per endpoint. Errors share the envelope documented in Error codes.

Pagination

List endpoints accept skip and take query parameters and return:

{
  "items": [ /* ... */ ],
  "total": 1248,
  "skip": 0,
  "take": 50
}

Always treat total as advisory — for very large traversals it may be a lower bound. Iterate by checking items.length === take until it isn't.

Authentication endpoints

SSO endpoints

Each SSO provider exposes the same shape under a provider-specific prefix. The provider names are microsoftsso, googlesso, oktasso, auth0sso.

SAML follows a different pattern:

See the individual SSO guides (Microsoft, Google, Okta, Auth0) for end-to-end setup.

Custom endpoint invocation

Example — calling a custom endpoint

curl -X POST "https://workspace.example.com/api/endpoints/run/similar-tickets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "screen flicker after firmware update",
    "productSku": "PRO-14",
    "limit": 5
  }'

[
  {
    "UID": "abc123…",
    "Type": "Ticket",
    "Id": "T-9182",
    "Subject": "Screen flicker after 5.1.2 firmware",
    "Body": "…"
  }
]

AI chat and tool metrics

Search configuration

Language codes are the usual two-letter codes, with -- for "any language". See Synonyms for what each list does.

Assistant configuration

See The search tool and Deep research for what these configure.

These are the operational metrics shown in Settings → Monitoring. There is currently no public Prometheus /metrics endpoint; see Monitoring for the roadmap and external-monitoring options.

Administration and diagnostics

The endpoints listed below require a system-administrator session; reads accept a read-only administrator, writes do not. The behaviour changes at the end of the section also cover endpoints an ordinary signed-in user can reach, and say so per entry.

Streamed responses (server-sent events)

Two endpoints that apply definitions to a workspace answer with a text/event-stream instead of a single JSON body, because compiling and rebuilding what a change touches outlasts what a browser — or a proxy in front of it — holds a plain request open for:

• POST /api/admin-agent/sessions/{id}/commit/approve
• POST /api/graph/import-definitions

The event sequence is the same for both: one event: log per step, then one event: result carrying exactly the payload the endpoint used to answer with, then event: done. A keepalive SSE comment (:) is written when nothing has happened for ten seconds. A caller that only wants the outcome can read the last result event and ignore the rest.

Two things to keep in mind when calling either directly:

• A refusal before the stream opens is still an ordinary status code. import-definitions checks the upload's content type first and answers a plain 400 for anything that is not a zip; the approval endpoint answers 404 for a session belonging to someone else.
• Closing the connection does not stop the work. Neither apply is tied to the request's cancellation — the approval runs on the server's shutdown token and the import takes no token at all — so a client that goes away loses the log, not the change.

Behaviour changes

• Access groups (signed-in user). PUT /api/groups/group, PUT /api/groups/group/{groupUID} and POST /api/groups/group/{groupUID}/delete answer 403 for a non-administrator caller when teams are disabled for the workspace, with the reason in the response body. An administrator with write access is unaffected — turning teams off takes the feature away from users, it does not freeze the groups the workspace is built on.
• Migration jobs (admin, write access). POST /api/migrations/cancel cancels the run and waits up to 30 seconds for it to stop, so a caller can rewrite or reset the task straight afterwards. It answers 409 if the migration's own code never honours its cancellation token. POST /api/migrations/reset-task-status answers 409 while a job is still running, rather than throwing a 500.
• Synthetic sample downloads (any signed-in, non-guest user). POST /api/node/download/synthetic/csv and POST /api/node/download/synthetic/jsonl no longer take a baseURL query parameter — the export now carries only the generated nodes' own fields and timestamp, with no Link, UID, Type or EdgeCount column. Drop the parameter from existing callers. See WithoutGraphMetadata().

User record field visibility

A _User node read by another signed-in user now returns only UID, Type, Timestamp, UserName, FirstName, LastName, FullName and Email. The administrative fields — the system-admin flag, roles, active, confirmed, one-time-password state, metadata and interface preferences — are withheld.

The projection applies to every generic reader:

• GET /api/node/{uid}
• POST /api/node/query
• POST /api/node/many/full
• POST /api/node/many/field (which answers BLOCKED for a field the caller may not read, on the plain and the interpolated branch alike)
• GET /api/groups/group/{groupUID}/users
• search results
• the CSV / JSON Lines / Excel downloads (POST /api/node/download/csv, download/jsonl, download/zip)

The user themselves and any system administrator — read-only included — still read the whole record, as do the self-or-admin endpoints under /api/users/user/{uid}.

Two consequences for integrations:

• Exports previously bypassed field-level access control entirely. It is now applied per node, and a cell the reader may not see is blanked. An integration parsing those exports may see fewer populated columns than before.
• A user is always granted access to their own user node, so node-type access configuration cannot lock someone out of their own record.

Search

The search engine is reachable from custom endpoints via Graph.CreateSearchAsync / CreateSearchAsUserAsync. There is no public HTTP route for ad-hoc search — wrap your own retrieval logic in a custom endpoint instead. This makes it impossible to bypass scoping or ranking via raw HTTP, and gives you a stable contract you can version.

Graph

The graph is reachable via the Q() chain from inside custom endpoints, the admin Shell, and Curiosity.Library in connectors. As with search, raw graph traversal is not exposed over HTTP for safety; expose what you need via endpoints.

Versioning

The Workspace is delivered as a versioned container image using calendar versioning (curiosityai/curiosity:26.6.66474 — YY.M.build, so 26.6 is June 2026 and 66474 is the running build number). The built-in endpoints listed on this page are part of that contract: any breaking change is called out in the release notes and a migration note in the changelog for that release.

Your custom endpoints are versioned by you. The recommended pattern is to put the version in the endpoint name (similar-tickets-v2) and keep the old endpoint live during the deprecation window.

Where to go next

• API Usage — the practical guide with end-to-end examples.
• Custom Endpoints — write the server side.
• Token scopes — pick the right token for the caller.
• Error codes — what every status code means and how to react.