API Contracts
Public API v1
Only POST /api/braid/{id} is a supported external contract in v1. Use a DataBraid API token in the Bearer header. Provider credentials are not API tokens and must never be sent by clients.
The generated endpoint reference includes cURL, JavaScript and Python examples. The OpenAPI source is kept in the repository as the machine-readable contract; the published page is static so production docs do not load the OpenAPI explorer runtime.
Response model
200: completed with public Output; body is JSON.204: completed without public Output; no response body.400: invalid graph, policy violation or invalid request.401: missing or invalid DataBraid token.403: disabled Braid or forbidden operation.429: plan or runtime limit reached.500: unexpected server or provider-wrapper failure.
Read X-DataBraid-Run-Id to correlate support and audit activity.
Internal surfaces
| Surface | Purpose | Stability |
|---|---|---|
/api/runs | Editor execution and run listing | Internal |
/api/runs/{id} | Session-owned run detail | Internal |
/api/runs/{id}/sinks | Short-lived browser sink delivery | Internal |
/api/runs/{id}/replay-input | One-time retained replay input | Internal |
/api/braids | Authenticated product CRUD | Internal |
/api/knowledge/* | Knowledge management and query support | Internal |
/api/mcp/* | MCP configuration and discovery | Internal |
Internal endpoints may change with the editor and are documented here for system comprehension, not third-party integration.