# Compatibility API (/v1) discovered API export

`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

- `If-None-Match` (header, string, optional)

## Responses

- **200**: Customer API OpenAPI document · body `object` · headers `ETag`
- **304**: Document unchanged; no response body. · headers `ETag`
- **401**: The server key is missing, invalid or not sent with the Bearer scheme. · body `UnauthorizedError`
- **403**: The server key and session token belong to different Sites, or the call came from a browser page on the public collector origin. · body `ForbiddenError`
- **404**: Unknown path or wrong method. · body `NotFoundError`
- **429**: Too many requests from one client IP. Wait for Retry-After. · body `RateLimitedError` · headers `Retry-After`
- **500**: The collector could not complete the request. Fail the protected action and do not retry automatically. · body `InternalError`
- **503**: The discovered document is not ready or unavailable. · body `DiscoveryUnavailableBody`

### Success body fields

- `openapi` ("3.1.1", required)
- `info` (object, required)
- `info.title` ("Discovered API", required)
- `info.version` ("1", required)
- `paths` (object, required)

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](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
curl -sS -X GET 'https://app.trytelltale.dev/v1/discovery/openapi.json' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"
```

```js tab=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](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.