Source workflow
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.
Run a scan
Woes detects source shape, extracts endpoint data, normalizes docs, generates Markdown, and prepares retrieval chunks.
Review coverage
Inspect source status, endpoint counts, generated Markdown, chunks, errors, and skipped content.
Configure auth when needed
Add encrypted credentials only when you need guarded API testing or live verification.
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.Status
Check whether the scan completed, partially completed, failed, or skipped content.
Endpoints
Confirm important methods, paths, summaries, parameters, request bodies, and responses.
Generated Markdown
Review the AI-readable endpoint evidence that support answers can cite.
Chunks
Check whether retrieval chunks are specific enough to answer customer questions.
Auth detection
Confirm detected auth requirements before configuring credentials.
Errors
Fix failed pages, malformed specs, oversized payloads, or missing source data.
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.
Re-enter secrets when rotating credentials or changing a stored auth configuration. Public API responses should not return plaintext credential values.
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.
- 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.
Maintenance rhythm
After every API release
After every API release
Rescan sources, review changed endpoints, and test the agent against new and changed behavior.
When support sees repeated confusion
When support sees repeated confusion
Add examples, troubleshooting notes, or error details to the source docs, then rescan and retest.
When credentials change
When credentials change
Rotate the stored credential, run a safe test request, and confirm old secrets do not appear in responses or logs.
When source coverage is partial
When source coverage is partial
Split large docs, add structured source files, or remove obsolete pages that conflict with current behavior.