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

# API Reference Overview

> Braintest API v2 base URL, API-KEY authentication, response envelope format, pagination, and server environments for partner integrations.

The Braintest API v2 lets partner systems administer psychological tests and cognitive roadmaps programmatically. This reference covers the base URL, how to authenticate, the JSON response envelope, pagination behavior, and available server environments.

## Base URL

All API requests are sent to the versioned base URL:

```text theme={"dark"}
https://braintest.ir/api/v2
```

## Authentication

Every request must include an `API-KEY` header containing your API key from the organizer panel:

```text theme={"dark"}
API-KEY: YOUR_API_KEY
```

For example:

```bash theme={"dark"}
curl -H "API-KEY: YOUR_API_KEY" https://braintest.ir/api/v2/record/
```

If the key is missing, malformed, or invalid, the API returns a `401 Unauthorized` error. If the key has been revoked or blocked, the API returns a `403 Forbidden` error.

See the [Authentication](/authentication) page for full details on obtaining and managing your API keys.

## Response envelope

Every JSON response from the Braintest API is wrapped in a standard envelope:

```json theme={"dark"}
{
  "data": {},
  "successful": true,
  "messages": []
}
```

* `data` — the actual response payload (varies by endpoint)
* `successful` — boolean indicating whether the request succeeded
* `messages` — array of informational or error strings

On error, `successful` is `false`, `data` is `null`, and `messages` contains one or more error descriptions. For a deeper explanation of the envelope structure and error handling patterns, see [Response Envelope](/concepts/response-envelope).

## Pagination

List endpoints return up to 30 items per page. To paginate, append the `page` query parameter to the URL:

```text theme={"dark"}
GET /record/?page=2
```

The response includes cursor links in the `next` and `previous` fields inside `data` when additional pages are available.