Curiosity

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.

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

© 2026 Curiosity. All rights reserved.