Authentication

The Woes REST API uses workspace API keys. Create a key in Settings → Keys, copy the full secret once, and store it in your server-side secret manager.

Workspace API keys start with woesk_. Widget keys are public install identifiers and are not accepted by REST API endpoints.

Bearer Token

Pass the key in the Authorization header.

curl https://woes.dev/api/v1/conversations \
  -H "Authorization: Bearer $WOES_API_KEY"

Try Requests In Mintlify

The generated Endpoint Reference pages include an interactive API playground. Paste your own woesk_ key into the Bearer token field, adjust the prefilled example parameters or JSON body, and click Send to run the call.

The playground runs against https://woes.dev. Use a test workspace key when creating conversations, messages, or issues from the docs.

Use a disposable, scoped test key in the docs playground. Do not paste a production integration key. Playground requests may transit the docs runtime when proxying is enabled. For production keys, run curl or SDK calls from your own backend and revoke playground test keys after use.

Quick API Examples

These examples use active public Woes API resources. The API key must be a workspace API key that starts with woesk_.

List conversations

curl "https://woes.dev/api/v1/conversations?status=open&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

Create a conversation

curl https://woes.dev/api/v1/conversations \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ticket_123",
    "subject": "Need help with auth",
    "customer": {
      "id": "cus_123",
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    }
  }'

Add a message

curl https://woes.dev/api/v1/conversations/{conversationId}/messages \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "body": "I am getting a 401 from POST /orders."
  }'

See Conversations for every supported conversation endpoint, request field, and response shape.

List issues

curl "https://woes.dev/api/v1/issues?statusCategory=new&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

Create an issue

curl https://woes.dev/api/v1/issues \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "OAuth redirect URI mismatch",
    "description": "Customer reports a redirect_uri mismatch on the production OAuth app.",
    "priority": "high",
    "customer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    },
    "tags": ["oauth", "production"]
  }'

See Issues for every supported issue endpoint, request field, and response shape.

List clients

curl "https://woes.dev/api/v1/clients?health=watch&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

See Clients for client aggregate fields, filters, and read-only boundaries.

List agents

curl "https://woes.dev/api/v1/agents?enabled=true&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

See Agents for public agent metadata, widget keys, and read-only boundaries.

Security Rules

Keep woesk_ keys on your backend.
Do not put REST API keys in widget snippets or client-side JavaScript.
Revoke keys from Settings → Keys when rotating credentials.
Each key is workspace-scoped; it cannot read or write another workspace.
Valid REST API calls are tracked against the key that authenticated the request.

Error Responses

Status	Code	Meaning
`401`	`unauthorized`	Missing, unknown, or revoked API key.
`401`	`key_expired`	API key has expired.
`403`	`insufficient_scope`	API key is missing the required scope.
`429`	`rate_limited`	Too many requests for the key.
`500`	`internal_error`	The API request could not be completed.

{
  "code": "unauthorized",
  "error": "A valid workspace API key is required."
}

For 429 rate_limited, back off and retry after a short delay. Public REST API requests are rate-limited per workspace API key.

​Authentication

​Bearer Token

​Try Requests In Mintlify

​Quick API Examples

​List conversations

​Create a conversation

​Add a message

​List issues

​Create an issue

​List clients

​List agents

​Security Rules

​Error Responses

Authentication

Bearer Token

Try Requests In Mintlify

Quick API Examples

List conversations

Create a conversation

Add a message

List issues

Create an issue

List clients

List agents

Security Rules

Error Responses