# Compatibility API (/v1) verification

`POST /v1/verify` · operationId `compatVerify`

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.

Uses the stricter actionVerdict from /api/v1/verify (analytics-only AI agent is excluded), returned in the v1 shape {verdict, score}. Scores are categorical (human 1, unknown 50, agent 99), never probabilities; unknown is not human. Failures are exactly {"error":"<code>"}. The request body is closed (sessionToken and actionId only); to forward Web Bot Auth headers use /api/v1/verify.

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

## Request body

Content-Type: application/json (required)

- `sessionToken` (string, required) · minLength 1, pattern `\S`: Browser SDK session token. Missing, empty or non-string is 400 bad_request; malformed, over 250 characters, shaped like a key or not signed by this collector is 401 unauthorized; a token this collector issued whose session expired, was revoked or was removed is 409 session_reinit_required.
- `actionId` (string, required) · pattern `^[a-z0-9_-]{1,64}$`: Lowercase on /v1; /api/v1 also accepts uppercase.

```json
{
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "actionId": "export_report"
}
```

## Responses

- **200**: Verdict · body `object`
- **400**: The request is invalid (invalid JSON, an unknown property, a missing or empty sessionToken, an invalid actionId or ID, or a body over 131072 bytes). Fix the request before sending it again. · body `BadRequestError`
- **401**: The server key is missing, invalid or not sent with the Bearer scheme, or the session token is invalid: malformed, over 250 characters, shaped like a key, or not signed by this collector. Check the key, then replace only the session token. · 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`
- **409**: The session token was issued by this collector but can no longer be verified: its session expired, was revoked (for example on consent withdrawal) or was removed, or identify tried to replace an established identity. Start a new browser session and get a new token; do not resend the old one. · body `SessionReinitRequiredError`
- **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**: A temporary Site configuration or browser session failure; the code names what is unavailable. Only verify may retry (three attempts, 0-250 ms then 0-500 ms jitter). · body `UnavailableBody`

### Success body fields

- `verdict` ("human" | "agent" | "unknown", required)
- `score` (1 | 50 | 99, 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 POST 'https://app.trytelltale.dev/v1/verify' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"sessionToken":"PASTE_BROWSER_SESSION_TOKEN","actionId":"export_report"}'
```

```js tab=fetch
const response = await fetch("https://app.trytelltale.dev/v1/verify", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
    "actionId": "export_report"
  }),
  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.