Compatibility API (/v1) discovered API export

View as Markdown

GET /v1/discovery/openapi.json · operationId compatDiscoveredOpenApi

For developers: your server sends this request with a server key; it is not a button in the dashboard.

Note

This is the compatibility API (/v1): it keeps the request and response shapes of the v1 agent-verification API that existing integrations were built on, so such an integration works unchanged. New integrations should use the /api/v1 operations, which return reasons, decision, policy and attribution and work with the server adapter.

The reviewed actions of /api/v1/discovery/openapi.json in the v1 DiscoveredOpenApiDocument shape: exactly openapi 3.1.1, info {title: Discovered API, version: 1} and paths, with ETag/If-None-Match. 503 discovery_unavailable while discovery is off for the Site, discovery_not_ready while it is on but nothing has been observed yet. Failures are exactly {"error":"<code>"}.

Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

Parameters

Responses

Success body fields

Failures are not verdicts. Error bodies follow the CompatError schema: error is one of bad_request, unauthorized, forbidden, not_found, session_reinit_required, rate_limited, internal_error, config_unavailable, session_unavailable, discovery_not_ready, discovery_unavailable, session_not_found. Errors and retries explains each code and what to do.

Example

curl
curl -sS -X GET 'https://app.trytelltale.dev/v1/discovery/openapi.json' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"
fetch
const response = await fetch("https://app.trytelltale.dev/v1/discovery/openapi.json", {
  method: "GET",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY
  },
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.