> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, authentication, request format and conventions shared by every Finowl endpoint.

The Finowl API is a small, predictable JSON API. Every endpoint takes a `POST` with a JSON body and returns JSON.

## Base URL

```text theme={null}
https://api.finowl.co
```

All endpoints are versioned under `/v1`. HTTPS is required.

## Endpoints

<CardGroup cols={2}>
  <Card title="Check an email" icon="envelope" href="/api-reference/breaches/email">
    `POST /v1/breaches/email`
  </Card>

  <Card title="Check a password" icon="key" href="/api-reference/breaches/password">
    `POST /v1/breaches/password`
  </Card>

  <Card title="Predict from a name" icon="signature" href="/api-reference/gender/name">
    `POST /v1/gender/name`
  </Card>

  <Card title="Predict from an email" icon="at" href="/api-reference/gender/email">
    `POST /v1/gender/email`
  </Card>

  <Card title="Predict from a username" icon="user" href="/api-reference/gender/username">
    `POST /v1/gender/username`
  </Card>

  <Card title="Predict in batch" icon="layer-group" href="/api-reference/gender/batch">
    `POST /v1/gender/batch`
  </Card>
</CardGroup>

## Authentication

Send your API key as a bearer token on every request.

```http theme={null}
Authorization: Bearer finowl_3f9a2c7e1b4d8a6f0e5c9b21.Xk8...
```

See [Authentication](/authentication) for how to create, store and rotate keys.

## Request format

* Method: `POST` for every endpoint. Other methods return `405 method_not_allowed`.
* Header: `Content-Type: application/json`. Anything else returns `415 json_required`.
* Body: a single JSON object, at most 128 KB.
* Unknown fields are rejected with `400 invalid_input`. This catches typos such as `contry` before they cost you a credit.
* `null` is not accepted for any field. Leave optional fields out instead.

## Response format

Successful responses return the result object directly, with no envelope for breach checks and a `data` envelope for gender predictions.

Errors always use the same shape:

```json theme={null}
{ "error": { "code": "invalid_input" } }
```

The full list of codes is on the [Errors](/concepts/errors) page.

## Conventions

| Topic | Behavior |
| - | - |
| Credits | 1 credit per lookup, 1 per batch item. See [Credits and billing](/concepts/credits). |
| Rate limit | 60 requests per minute per account. See [Rate limits](/concepts/rate-limits). |
| Timeouts | Lookups usually finish in well under a second. Set your client timeout to at least 40 seconds. |
| Forward compatibility | New response fields can appear at any time. Ignore fields you do not recognize. |
| Browser use | The API does not send CORS headers. Call it from your server, never from a browser or mobile app. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.