> ## Documentation Index
> Fetch the complete documentation index at: https://docs.woes.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Test and integrate the Woes REST API with workspace API keys, generated endpoint pages, and runnable examples.

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

<CardGroup cols={2}>
  <Card title="Run your first request" icon="play" href="/api/authentication">
    Create a `woesk_` key, paste it into the playground, and send a safe test
    request against your workspace.
  </Card>

  <Card title="API fundamentals" icon="book-open" href="/api/overview">
    Review base URLs, scopes, response conventions, pagination, limits, and
    safe integration patterns.
  </Card>

  <Card title="Conversations" icon="messages" href="/api/conversations">
    Create support conversations, update status and priority, and append user
    or assistant messages.
  </Card>

  <Card title="Issues" icon="circle-alert" href="/api/issues">
    Create, filter, read, and update customer support issues.
  </Card>

  <Card title="Clients" icon="building-2" href="/api/clients">
    Read client/account aggregates, contacts, health, and recent activity.
  </Card>

  <Card title="Agents" icon="bot" href="/api/agents">
    Read agent metadata and public widget keys for install automation.
  </Card>

  <Card title="Sources" icon="database" href="/api/sources">
    Create, inspect, publish, delete, and rescan API context sources.
  </Card>

  <Card title="Definitions" icon="tags" href="/api/definitions">
    Sync tags, statuses, priorities, and customer custom field definitions.
  </Card>

  <Card title="Usage and analytics" icon="chart-line" href="/api/usage">
    Read monthly usage meters, per-key API usage, and sanitized analytics
    aggregates.
  </Card>

  <Card title="Keys and scopes" icon="key" href="/api/keys">
    Understand `woesk_` API keys, resource scopes, rotation, usage tracking,
    and the difference between API keys and widget keys.
  </Card>
</CardGroup>

## How The Reference Is Organized

| Section            | Use it for                                                                                                 |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| API basics         | Overview, authentication, scopes, key handling, usage tracking, and route boundaries.                      |
| Runtime guides     | Route map plus customer-facing widget and survey routes that are not authenticated with `woesk_` API keys. |
| Endpoint Reference | Generated OpenAPI pages with runnable examples, schemas, and categorized REST resources.                   |

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.

<Steps>
  <Step title="Create a workspace API key">
    Open Woes **Settings → Keys**, create a workspace API key, and copy the
    full `woesk_` secret once.
  </Step>

  <Step title="Open an endpoint page">
    Choose an endpoint in the **Endpoint Reference** section of this tab.
  </Step>

  <Step title="Paste your Bearer token">
    Add a disposable test key to the authorization field in the playground.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Active Resources

| Resource      | Status | Guide                               |
| ------------- | ------ | ----------------------------------- |
| Conversations | Active | [Conversations](/api/conversations) |
| Issues        | Active | [Issues](/api/issues)               |
| Clients       | Active | [Clients](/api/clients)             |
| Agents        | Active | [Agents](/api/agents)               |
| Sources       | Active | [Sources](/api/sources)             |
| Definitions   | Active | [Definitions](/api/definitions)     |
| Usage         | Active | [Usage](/api/usage)                 |
| Analytics     | Active | [Analytics](/api/analytics)         |

## Related Public Routes

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.

| Route family    | Guide                           |
| --------------- | ------------------------------- |
| Widget runtime  | [Widget runtime](/api/widget)   |
| Survey delivery | [Survey delivery](/api/surveys) |

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

<Tip>
  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.
</Tip>