> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyformat.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Check API Key
> Verify an API key without triggering a billable operation
Confirms the caller's API key is active and names its owning organization. Unversioned — the same endpoint works for v2 and v3 keys.
* **200** — the key is valid; response body carries `organization_id` (and `organization_name` when available).
* **401** — standard [error envelope](/api-reference/errors) with `error_code` `MISSING_API_KEY` (no key sent) or `INVALID_API_KEY` (key not recognised).
Nothing is billed and no run is created, so it's cheap to call as a probe before the first real request. It hits the same `/me/organization/` round-trip every authenticated request runs, so a successful check also warms the org cache.
```bash curl theme={null}
curl -X GET 'https://api.anyformat.ai/key-check/' \
-H 'Authorization: Bearer YOUR_API_KEY'
```
```python Python (requests) theme={null}
import requests
response = requests.get(
"https://api.anyformat.ai/key-check/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
response.raise_for_status()
print(response.json()["organization_id"])
```
```javascript JavaScript theme={null}
const response = await fetch('https://api.anyformat.ai/key-check/', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
if (!response.ok) throw new Error(`Invalid API key: ${response.status}`);
const { organization_id, organization_name } = await response.json();
```
```json Response (200 OK) theme={null}
{
"valid": true,
"organization_id": "7f4a1c2e-0000-4000-8000-000000000001",
"organization_name": "Acme Corp"
}
```
```json Response (401 Unauthorized) theme={null}
{
"error": "Invalid API key",
"detail": "The provided API key is not recognised.",
"error_code": "INVALID_API_KEY",
"retryable": false,
"request_id": "a1b2c3d4e5f67890abcdef1234567890"
}
```
## OpenAPI
````yaml GET /key-check/
openapi: 3.1.0
info:
title: anyformat API
description: >
Document extraction and workflow automation API.
AnyFormat lets you define extraction workflows that pull structured data
from any document — PDFs, images, scanned files, or plain text. Upload a
file, run it through a workflow, and get back structured fields with
confidence scores and source evidence.
## Quick start
See the [Quick start
guide](https://docs.anyformat.ai/api-reference/introduction) for a
walkthrough.
## Authentication
All endpoints (except `/health/`) require a Bearer token in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from
[app.anyformat.ai/api-key](https://app.anyformat.ai/api-key).
## Versioning
Endpoints are versioned by path prefix (`/v2/`, `/v3/`). Every response
under
a versioned prefix includes `X-API-Version`.
version: 2.0.0
servers:
- url: https://api.anyformat.ai
description: API server
security: []
tags:
- name: workflows
description: >-
Workflows define extraction templates — what fields to extract from
documents. Create workflows, upload files, run extractions, and fetch
results.
- name: files
description: >-
File collections group uploaded documents and track their extraction
progress. Upload files, check status, and retrieve extraction results.
- name: suggestions
description: >-
AI-powered schema and workflow suggestion endpoints for the AnyFormat
webapp. Authenticated with a Cognito JWT rather than an API key.
- name: document-packets
description: >-
Document packets group uploaded documents for a workflow (v3). Address a
packet directly to (re-)run its workflow.
- name: runs
description: >-
Extraction runs — the v3 first-class result entity. Each run is a single
execution of a workflow against a document packet; fetch its status and
results flat by run id.
- name: health
description: Health check endpoints to verify API availability.
paths:
/key-check/:
get:
tags:
- health
summary: Key Check
description: >-
Validate the caller's API key.
Success (200): the key is active and the response names its
organization and granted scopes. Failure (401): the standard error
envelope with
``error_code`` set to ``MISSING_API_KEY`` (no key sent) or
``INVALID_API_KEY`` (key sent but not recognised).
Reuses the same ``/me/organization/`` round-trip that every
authenticated request already runs, so a call here warms the same
cache — cheap to invoke as a probe before the first real request.
operationId: key_check_key_check__get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/KeyCheckResponse'
headers:
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
'401':
description: Authentication failed — missing, invalid, or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
AUTH_FAILED:
value:
error: Authentication failed.
detail: Authentication failed.
error_code: AUTH_FAILED
retryable: false
request_id: req_abc123
'429':
description: >-
Rate limited — retry after the `Retry-After` header. Default
windows: 60 requests/minute for extraction submission, 600
requests/minute for general endpoints.
headers:
Retry-After:
description: Seconds until the next request is allowed.
schema:
type: integer
X-RateLimit-Limit:
description: Requests allowed per window (60s).
schema:
type: integer
X-RateLimit-Remaining:
description: Requests remaining in the current window.
schema:
type: integer
X-RateLimit-Reset:
description: Seconds until the current window resets.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
RATE_LIMITED:
value:
error: Rate limit exceeded — retry after backoff.
detail: Rate limit exceeded — retry after backoff.
error_code: RATE_LIMITED
retryable: true
request_id: req_abc123
security:
- ApiKeyAuth: []
components:
schemas:
KeyCheckResponse:
properties:
valid:
type: boolean
title: Valid
description: >-
Always `true` — a failed check returns the standard error envelope
with `error_code` `MISSING_API_KEY` or `INVALID_API_KEY`.
examples:
- true
organization_id:
type: string
title: Organization Id
description: UUID of the organization the key belongs to.
examples:
- 7f4a1c2e-0000-4000-8000-000000000001
organization_name:
anyOf:
- type: string
- type: 'null'
title: Organization Name
description: >-
Display name of the owning organization, when the backend surfaces
it.
examples:
- Acme Corp
scopes:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Scopes
description: >-
Scopes granted to the key (`read`, `write`). `null` when the backend
does not report them.
examples:
- - read
- write
type: object
required:
- valid
- organization_id
title: KeyCheckResponse
description: Confirms the API key is valid and names its owning organization.
ErrorEnvelope:
type: object
title: ErrorEnvelope
description: >-
Uniform error response. `retryable=true` means the same request may
succeed on retry (with backoff); `retryable=false` means the caller must
change the request before retrying.
required:
- error
- detail
- error_code
- retryable
- request_id
properties:
error:
type: string
description: Short human-readable summary.
detail:
description: >-
Machine-readable detail. String for most errors; list of field
errors for validation failures.
oneOf:
- type: string
- type: array
items:
type: object
error_code:
type: string
description: Stable identifier for programmatic handling.
examples:
- VALIDATION_ERROR
- AUTH_FAILED
- NOT_FOUND
- PRECONDITION_FAILED
- RATE_LIMITED
- INTERNAL_ERROR
- GATEWAY_TIMEOUT
retryable:
type: boolean
description: True when the caller should retry (with backoff for 429/412/5xx).
request_id:
type: string
description: Correlates this response with server logs.
securitySchemes:
ApiKeyAuth:
type: http
description: >-
API key issued from app.anyformat.ai/api-key. Send as `Authorization:
Bearer `.
scheme: bearer
````