API reference

Reference for every public endpoint of the Discence REST API: authentication, workspaces, agents, threads, uploads, webhooks, and billing. The machine-readable contract is the OpenAPI 3.1 document.

Download the OpenAPI specification (JSON) · OpenAPI 3.1 · base /api/v1

Authentication

Session cookie

Sign in with email and password (POST /api/auth/sign-in/email) or through OAuth 2.0 with a configured provider (POST /api/auth/sign-in/social, then the provider callback). Both issue the better-auth.session_token cookie, valid seven days.

Single sign-on (SAML 2.0 / OIDC)

Workspaces that federate identity sign in through a SAML 2.0 or OIDC provider registered by a super administrator. POST /api/auth/sign-in/sso with the provider's id, domain, or the user's email returns the identity provider URL to redirect to; its callback issues the same session cookie. Group claims from the provider map to application roles on every sign-in.

API keys

Workspace admins create keys with POST /api/v1/api-keys. Send the key in the x-api-key header or as a Bearer token. The full value is shown once at creation; the platform stores only its SHA-256 hash. A key acts with its creator's current role in the workspace.

Workspace selection

Members of several workspaces pick one per request with the x-workspace-id header. API keys are bound to their workspace and ignore this header.

Errors

Failures return an error object. Validation failures add a details list and use status 400; 401 means missing or invalid credentials, 403 an insufficient role, 404 a missing resource.

{ "error": "Validation failed", "details": [{ "field": "name", "message": "Required" }] }

Webhooks

Register endpoints with POST /api/v1/webhooks to subscribe to workspace events. Each registration stores a secret reserved for signing outbound X-Hub-Signature-256 deliveries.

File transfer

Uploads use three steps: declare the file with POST /api/v1/uploads, stream bytes to the returned putUrl, then confirm with POST /api/v1/uploads/<id>/complete.

Endpoints