Skip to main content

​
API Reference

Use the Woes REST API from server-side integrations to work with the same workspace-scoped records used by the Woes operator app: conversations, messages, issues, client aggregates, agent metadata, API context sources, definitions, usage meters, and sanitized analytics. The generated endpoint pages in this tab come from openapi.json. They include runnable request builders, schemas, examples, error responses, and Bearer-token authentication.

Run your first request

Create a woesk_ key, paste it into the playground, and send a safe test request against your workspace.

API fundamentals

Review base URLs, scopes, response conventions, pagination, limits, and safe integration patterns.

Conversations

Create support conversations, update status and priority, and append user or assistant messages.

Issues

Create, filter, read, and update customer support issues.

Clients

Read client/account aggregates, contacts, health, and recent activity.

Agents

Read agent metadata and public widget keys for install automation.

Sources

Create, inspect, publish, delete, and rescan API context sources.

Definitions

Sync tags, statuses, priorities, and customer custom field definitions.

Usage and analytics

Read monthly usage meters, per-key API usage, and sanitized analytics aggregates.

Keys and scopes

Understand woesk_ API keys, resource scopes, rotation, usage tracking, and the difference between API keys and widget keys.

​
How The Reference Is Organized

Product setup guides live in the Docs tab. API contracts, route behavior, request examples, and generated endpoint pages live here.

​
Test Calls In The Docs

The endpoint pages in this API Reference tab are generated from openapi.json and include interactive request builders. Use them when you need exact request parameters, body schemas, response examples, and test calls.
1

Create a workspace API key

Open Woes Settings → Keys, create a workspace API key, and copy the full woesk_ secret once.
2

Open an endpoint page

Choose an endpoint in the Endpoint Reference section of this tab.
3

Paste your Bearer token

Add a disposable test key to the authorization field in the playground.
4

Send the request

Review the example parameters or body, then run the request against https://woes.dev. Calls are made against your workspace and count toward public API usage.
API keys are server-side secrets. Do not place woesk_ keys in browser snippets, frontend apps, customer-visible docs, or mobile clients. Use a disposable test key in the docs playground and revoke it after use. If you need scoped playground keys, create them through backend or administrative tooling until the Settings scope picker is available. For production keys, run requests from your own backend.

​
Active Resources

Widget and survey routes are active customer-facing surfaces, but they are not authenticated with woesk_ REST API keys and they do not appear in the generated /api/v1 endpoint reference.

​
Response Boundaries

REST API responses are scoped to the workspace attached to the API key. They do not include raw key material, workspace ids, service-role details, provider/model internals, operator-only debug traces, system prompts, or another workspace’s data.
Use the generated endpoint pages for exact parameters, request bodies, schemas, and runnable examples. Use the linked resource notes above when you need the extra workflow context behind a resource.
Last modified on July 3, 2026