Skip to main content

​
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.

​
Bearer Token

Pass the key in the Authorization header. 
curl https://woes.dev/api/v1/conversations \
  -H "Authorization: Bearer $WOES_API_KEY"

​
Quick API Examples

These examples use the Conversations API because it is the first public Woes API surface. 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.

​
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.

​
Error Responses

StatusCodeMeaning
401unauthorizedMissing, unknown, or revoked API key.
401key_expiredAPI key has expired.
429rate_limitedToo many requests for the key.
500internal_errorThe API request could not be completed.
{
  "code": "unauthorized",
  "error": "A valid workspace API key is required."
}