# API overview

> The Fingerly HTTP API: regional base URLs, the two kinds of key, JSON conventions, and the endpoints your SDKs and your server call.

Last updated: 2026-09-17

The Fingerly API is a small JSON-over-HTTPS API with three audiences. Client SDKs call the **client API** with a public key to identify visitors. Your backend calls the **server API** with a secret key to read what was identified. Your automation calls the **management API** with a management key to manage keys, webhook endpoints and risk weights. Most integrations never call the client API directly: the SDKs do.

## Base URL

Each region has its own API, and every key belongs to one region. Use the base URL of your key's region.

| Region | Base URL | Keys | Status |
| --- | --- | --- | --- |
| United States | `https://us.api.fingerly.io/api/v1` | `fly_pk_us_…`, `fly_sk_us_…`, `fly_px_us_…` | Available |
| European Union | `https://eu.api.fingerly.io/api/v1` | `fly_pk_eu_…`, `fly_sk_eu_…`, `fly_px_eu_…` | Coming soon |

Management keys, `fly_mk_us_…` and `fly_mk_eu_…`, belong to a region the same way.

The SDKs read the region from the key and choose the base URL for you. A key sent to another region's API is refused. See [regions and data residency](https://docs.fingerly.io/docs/regions).

## Endpoints

| Endpoint | Key | Purpose |
| --- | --- | --- |
| [`GET /events`](https://docs.fingerly.io/reference/list-events) | Secret | List events in a time window. |
| [`GET /events/{request_id}`](https://docs.fingerly.io/reference/get-event) | Secret | Read one event with its archived detail. |
| [`POST /identify`](https://docs.fingerly.io/reference/identify) | Public | Submit a signal report and get the verdict. |
| [`POST /events/{request_id}/supplement`](https://docs.fingerly.io/reference/deferred-report) | Public | Attach the deferred report to an identification. |
| [`POST /attestation/challenge`](https://docs.fingerly.io/reference/attestation-challenge) | Public | Issue a one-time attestation challenge for the Android SDK. |
| [`/management/…`](https://docs.fingerly.io/reference/management/overview) | Management | Manage SDK keys, proxy keys, webhook endpoints and risk weights. |

## Conventions

- Request and response bodies are JSON (`application/json`). Unknown request fields are rejected.
- Request bodies are limited to 1 MiB. Client API requests may be sent with `Content-Encoding: gzip`, and the limit applies after decompression.
- Timestamps are RFC 3339 in UTC, such as `2026-09-16T09:41:12.482Z`.
- Request IDs are UUIDv7, so they sort by time and carry their own timestamp.
- Optional response fields are omitted when they do not apply, unless a page says a field is `null`.
- Every response carries an `X-Request-Id` header. Include it when you contact support.

## Versioning

The version is part of the path, `/api/v1`. Within a version, Fingerly adds fields and endpoints but does not remove or rename them, and never changes what a field means. Write clients that ignore fields they do not know.

Signal names are permanent too. If a detection ever changes what it measures, it gets a new name.

## Health

`GET /api/v1/healthz` answers when the API process is up; `GET /api/v1/readyz` answers when it can serve traffic. Neither needs a key.

## OpenAPI

The whole public API is described in an OpenAPI 3.1 document, with a Postman collection generated from it. See [OpenAPI and Postman](https://docs.fingerly.io/reference/openapi).

- [Authentication](https://docs.fingerly.io/reference/authentication): Public, secret, proxy and management keys.
- [Errors](https://docs.fingerly.io/reference/errors): Statuses, codes and what to do.