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

POST /api/login/create : Exchange a username/password for a session JWT. : Body { "user": "...", "password": "..." } : Returns { "token": "...", "expiresAt": "..." }

GET /api/login/check : Verify a session JWT is still valid. : Auth Bearer (session JWT) : Returns { "user": { "uid": "...", "name": "..." } } or 401.

POST /api/login/password/change : Change the calling user's password. : Auth Bearer (session JWT) : Body { "oldPassword": "...", "newPassword": "..." }

POST /api/login/password/reset : Start a password-reset flow for an email address. : Body { "email": "..." }

SSO endpoints

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

GET /api/{provider}/config : Read the current SSO config (admin only).

POST /api/{provider}/config : Update the SSO config (admin only).

GET /api/{provider}/get-login-url : Returns the URL clients should redirect to when starting an SSO login.

GET /api/{provider}/completed-login-attempt : Callback the identity provider redirects back to after the user authenticates. Configure this exact path as the redirect URI in your IdP.

SAML follows a different pattern:

GET /api/saml/createrequest/{providerName}/{issuer}/{destination} : Builds an AuthnRequest for the configured provider.

POST /api/saml/acs : Assertion Consumer Service endpoint — the SAML callback.

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

Custom endpoint invocation

POST /api/endpoints/run/{name} : Invoke an endpoint by name as the authenticated user. Used by the workspace's own front-end and by any caller using a user session JWT. : Auth Bearer (session JWT, or API token with the endpoints:run scope) : Body the request shape your endpoint expects (Body.FromJson<T>()). : Returns whatever the endpoint returns (typed JSON).

POST /api/endpoints/token/run/{name} : Invoke an endpoint with an endpoint token. The endpoint's CurrentUser is the token's associated user (or null if the token is system-scoped). : Auth Bearer (endpoint token) : Body / Returns same as /run/{name}.

POST /api/cce/{name} : Lower-level invocation alias used by the front-end. Same auth and behavior as /api/endpoints/run/{name}.

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

POST /api/chatai/chat : Send a turn to the chat assistant. Used by the built-in chat view.

GET /api/chatai/tools/metrics : Per-tool invocation metrics (counts, average latency, error rate). Admin only.

GET /api/endpoints/metrics : Per-endpoint invocation metrics. Admin only.

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.

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 (curiosityai/curiosity:vX.Y.Z). The built-in endpoints listed on this page are part of that contract: breaking changes ship with a major version bump and a migration note in the release notes.

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.