Authentication

Every protected API endpoint expects an OAuth access token, sent as a bearer token in the Authorization header. This page covers how to send it and the conventions that apply to every request.

Getting a token

You obtain an access token through Epismo's OAuth flow (see OAuth for the full sequence). If you are integrating the CLI or an MCP client, use the product-specific token endpoints instead, which return a ready-to-use access token (and a refresh token) directly.

Access tokens are short-lived. When one expires, exchange the refresh token for a new access token rather than sending the user through sign-in again. Requests with a missing or expired token return 401.

Sending the token

curl https://api.epismo.ai/v1/packs/search \
  -H "authorization: Bearer $EPISMO_TOKEN" \
  -H "content-type: application/json" \
  -d '{"type":"context","query":"onboarding"}'

Scopes

Tokens carry scopes that determine what they may do:

• Read endpoints require a read scope.
• Mutation endpoints (create, update, delete) require a write scope.

If a token lacks the scope an endpoint needs, the request returns 403. Request only the scopes your integration actually uses.

Workspace context

Many /v1 endpoints can act inside a specific workspace. Pass the workspace as a workspaceId query parameter:

curl "https://api.epismo.ai/v1/projects?workspaceId=$WORKSPACE_ID" \
  -H "authorization: Bearer $EPISMO_TOKEN"

If you omit workspaceId, the request runs in the token's default context, or in personal space when the token has none. For predictable behavior, especially in automated systems, pass workspaceId explicitly.

Request conventions

These hold across the API, so examples stay consistent:

• Send JSON bodies with content-type: application/json.
• Dates use YYYY-MM-DD.
• Create and update calls take a single scope; search calls take scopes.
• Updates use PATCH semantics unless a page says otherwise: omitted fields are left unchanged.

When a request fails, the response carries an error field. See Errors for the full list of status codes and how to handle them.