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

> Planned public API categories for building with Woes.

The Woes public API will let teams connect Woes to their own products, internal tools, reporting workflows, and support operations.

This section is a public API map. It describes the categories Woes plans to expose, but it does not publish endpoint paths, request schemas, response schemas, SDKs, or production limits yet.

<Warning>
  Do not build production integrations from this section until endpoint-level documentation is published.
</Warning>

## Category map

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-authentication">
    Server credentials, scopes, rotation, widget keys, and conversation secrets.
  </Card>

  <Card title="Workspaces" icon="building" href="/api-workspaces">
    Workspace metadata, members, roles, tags, custom fields, macros, and automations.
  </Card>

  <Card title="Conversations" icon="messages-square" href="/api-conversations">
    Conversation lifecycle, assignment, state, messages, notes, and issue links.
  </Card>

  <Card title="Customers" icon="users" href="/api-customers">
    Customer profiles, external IDs, traits, account context, and channel identities.
  </Card>

  <Card title="Knowledge" icon="brackets-curly" href="/api-knowledge">
    API Context sources, scans, endpoint evidence, chunks, and test metadata.
  </Card>

  <Card title="Agent" icon="bot" href="/api-agent">
    Lab runs, drafts, citations, confidence signals, handoff events, and verification traces.
  </Card>

  <Card title="Channels" icon="inbox" href="/api-channels">
    Live chat, Discord, widget sessions, email readiness, and channel configuration.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-webhooks">
    Event subscriptions for conversations, messages, customers, issues, sources, and agent events.
  </Card>

  <Card title="Errors and limits" icon="triangle-alert" href="/api-errors-and-limits">
    Error categories, pagination, idempotency, rate limits, and retry behavior.
  </Card>
</CardGroup>

## Design principles

| Principle            | What it means                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| Workspace scoped     | Public endpoints should operate inside one workspace boundary.                                          |
| Least privilege      | Credentials and scopes should grant only the access an integration needs.                               |
| Widget separation    | Browser-facing widget routes should stay narrower than authenticated workspace APIs.                    |
| Grounded agent data  | Agent output should include evidence, confidence, and handoff state where relevant.                     |
| Redaction first      | Sensitive values should be redacted before being returned, logged, or sent to AI workflows.             |
| Stable before launch | Endpoint behavior should be stable enough for customer integrations before detailed docs are published. |

## Planned documentation layers

<Steps>
  <Step title="Category map">
    The current docs define the major API surfaces and boundaries.
  </Step>

  <Step title="Endpoint reference">
    Future docs should add paths, methods, parameters, request bodies, responses, examples, and auth scopes.
  </Step>

  <Step title="Integration guides">
    Future guides should show common workflows, such as creating a conversation, syncing customers, or subscribing to webhooks.
  </Step>

  <Step title="SDKs and changelog">
    SDK docs and versioned API changes should come after the endpoint contract is stable.
  </Step>
</Steps>

## Intentionally not documented yet

* Endpoint paths.
* Request and response schemas.
* Authentication scopes.
* SDKs.
* Webhook signing format.
* Versioning policy.
* Production rate limits.
* SLA or compliance claims.

Those details will be added when the public API is ready for integration work.