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

> Add, scan, review, and test the API sources that ground Woes answers.

API Context is the source of truth for grounded developer support. It turns specs, docs, examples, schemas, and websites into endpoint evidence that operators can inspect and the agent can cite.

<Warning>
  A successful upload is not the same as trusted context. Review generated endpoints, Markdown, chunks, and auth detection before relying on the agent.
</Warning>

## Source workflow

<Steps>
  <Step title="Add a source">
    Choose the source type that best represents your API. Prefer structured sources for endpoint contracts and narrative docs for examples or behavior notes.
  </Step>

  <Step title="Run a scan">
    Woes detects source shape, extracts endpoint data, normalizes docs, generates Markdown, and prepares retrieval chunks.
  </Step>

  <Step title="Review coverage">
    Inspect source status, endpoint counts, generated Markdown, chunks, errors, and skipped content.
  </Step>

  <Step title="Configure auth when needed">
    Add encrypted credentials only when you need guarded API testing or live verification.
  </Step>

  <Step title="Retest the agent">
    Ask real support questions and confirm answers cite the updated source.
  </Step>
</Steps>

## Choose the right source

| Source type | Use it for                                                                                  | Watch for                                                        |
| ----------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| OpenAPI     | Endpoint shape, parameters, schemas, request bodies, responses, servers, and auth metadata. | Missing examples, stale descriptions, incomplete error behavior. |
| Markdown    | Guides, tutorials, troubleshooting, and behavior explanations.                              | Ambiguous language, duplicated old docs, missing endpoint names. |
| JSON        | Structured endpoint or schema data from internal tools.                                     | Unexpected nesting, unclear labels, unredacted sensitive values. |
| Website     | Published API docs or developer guides.                                                     | Crawl gaps, blocked pages, same-origin limits, partial coverage. |

## Review scan results

After scanning, inspect the source detail view.

<CardGroup cols={2}>
  <Card title="Status" icon="activity">
    Check whether the scan completed, partially completed, failed, or skipped content.
  </Card>

  <Card title="Endpoints" icon="route">
    Confirm important methods, paths, summaries, parameters, request bodies, and responses.
  </Card>

  <Card title="Generated Markdown" icon="file-text">
    Review the AI-readable endpoint evidence that support answers can cite.
  </Card>

  <Card title="Chunks" icon="boxes">
    Check whether retrieval chunks are specific enough to answer customer questions.
  </Card>

  <Card title="Auth detection" icon="key-round">
    Confirm detected auth requirements before configuring credentials.
  </Card>

  <Card title="Errors" icon="triangle-alert">
    Fix failed pages, malformed specs, oversized payloads, or missing source data.
  </Card>
</CardGroup>

## Configure API auth

Credentials let Woes run guarded tests and live verification. They are stored separately from source content.

Use the safest credential that can prove the behavior:

* No auth when endpoints are public.
* API key header or query parameter for simple key-based APIs.
* Bearer token for token-based APIs.
* Basic auth when the upstream API requires it.
* OAuth client credentials for machine-to-machine token flows.
* Session token request when the API requires a login call before requests.
* Custom header, custom query, cookie, HMAC, AWS SigV4, or mTLS metadata when those schemes match the API.

<Note>
  Re-enter secrets when rotating credentials or changing a stored auth configuration. Public API responses should not return plaintext credential values.
</Note>

## Live API verification

Live verification is useful when the customer question depends on current API behavior.

Good candidates:

* Safe read-only requests.
* Authentication checks.
* Documented example requests.
* Response shape confirmation.
* Reproducing a non-destructive error.

Avoid live verification when:

* The request may create, update, or delete production data.
* The endpoint behavior is unclear.
* Credentials are too broad.
* The customer has not provided enough context.
* The question requires account-specific judgment.

## Grounding rules

The agent should not invent:

* Endpoints.
* Fields.
* Auth rules.
* Rate limits.
* Error codes.
* Response bodies.
* Production behavior.

When evidence is missing, the expected result is clarification, a citation gap, or handoff to an operator.

## Maintenance rhythm

<AccordionGroup>
  <Accordion title="After every API release">
    Rescan sources, review changed endpoints, and test the agent against new and changed behavior.
  </Accordion>

  <Accordion title="When support sees repeated confusion">
    Add examples, troubleshooting notes, or error details to the source docs, then rescan and retest.
  </Accordion>

  <Accordion title="When credentials change">
    Rotate the stored credential, run a safe test request, and confirm old secrets do not appear in responses or logs.
  </Accordion>

  <Accordion title="When source coverage is partial">
    Split large docs, add structured source files, or remove obsolete pages that conflict with current behavior.
  </Accordion>
</AccordionGroup>