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

# Braintest API: Psychological Tests & Cognitive Roadmaps

> Integrate psychological tests and cognitive roadmaps into your platform with the Braintest API. Built for partners and developers in Iran.

Braintest is a psychological testing platform that lets partners administer validated tests (MCMI, NEO, DASS-21, PHQ-9, and more) and AI-powered cognitive roadmaps through a single REST API. Whether you are building a wellness app, a counseling platform, or an HR assessment tool, you can embed Braintest tests and retrieve results without managing test content or scoring logic yourself.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get your first test result in minutes with a step-by-step walkthrough.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Learn how to obtain and use your API key to authenticate requests.
  </Card>

  <Card title="Records" icon="clipboard" href="/concepts/records">
    Understand standalone test records, their lifecycle, and status codes.
  </Card>

  <Card title="Roadmaps" icon="map" href="/concepts/roadmaps">
    Explore multi-test packages with AI-powered combined analysis.
  </Card>
</CardGroup>

## Integration patterns

The Braintest API supports two main integration patterns. Choose the one that fits your use case.

Every record and roadmap payload includes a `tests_auth_required` flag copied from your organizer setting. It controls whether authentication uses a two-step SMS flow (default) or completes on a single call.

### Standalone tests

Use this pattern when you want to administer a single psychological test to a participant.

1. List available records and pick one with `status: 2` (ready) and `auth_required: true`.
2. Call `POST /record/{token}/auth/` with the participant profile.
3. When `tests_auth_required` is `true`, finish authentication by calling `PUT /record/{token}/auth/verify/` with the returned `draft_token` and the SMS code. When it is `false`, the profile is created immediately.
4. Fetch the test questions.
5. Submit the participant answers.
6. Retrieve the result in JSON or HTML format.

### Cognitive roadmaps

Use this pattern when you want to run a multi-test package and receive an AI-generated combined analysis.

1. List available roadmaps and pick one with `status: 2` (ready).
2. Call `POST /roadmap/{token}/auth/` with the shared mobile and one profile per role.
3. When `tests_auth_required` is `true`, finish authentication by calling `PUT /roadmap/{token}/auth/verify/` with the `draft_token` and the SMS code. When it is `false`, all role profiles are created immediately.
4. For each test record in the roadmap, fetch questions and submit answers.
5. Queue AI analysis generation.
6. Poll the generation status until it completes.
7. Retrieve the combined roadmap result in JSON or HTML format.

<Note>
  For roadmap records, always authenticate through `/roadmap/{token}/auth/` instead of `/record/{token}/auth/`. Roadmap authentication links all participant profiles to every record in the package automatically.
</Note>