# Braintest API

## Docs

- [Braintest API: Psychological Tests & Cognitive Roadmaps](https://docs.braintest.ir/index.md): Integrate psychological tests and cognitive roadmaps into your platform with the Braintest API. Built for partners and developers in Iran.
- [Get Started with the Braintest API](https://docs.braintest.ir/quickstart.md): Make your first Braintest API call: verify your key, authenticate a participant (SMS or instant), submit answers, and retrieve a test result.
- [Authenticate with the Braintest API](https://docs.braintest.ir/authentication.md): Learn how to obtain your Braintest API key from the organizer panel and send it in the API-KEY header on every request.
- [Test Records: Standalone Psychological Tests](https://docs.braintest.ir/concepts/records.md): Learn what a test record is, how it moves through its lifecycle, and how status codes and auth_required guide your integration flow.
- [Cognitive Roadmaps: Multi-Test AI Analysis Packages](https://docs.braintest.ir/concepts/roadmaps.md): Discover cognitive roadmaps: multi-test packages with AI-powered combined analysis, roles, and async generation for deeper insights.
- [Participant Profiles and Authentication](https://docs.braintest.ir/concepts/profiles.md): How Braintest participant profiles work: required fields, external IDs, and the two authentication paths (SMS verification or instant).
- [API Response Envelope Format](https://docs.braintest.ir/concepts/response-envelope.md): Understand the unified JSON envelope that wraps every Braintest API response, including success and error shapes.
- [Run a Standalone Psychological Test](https://docs.braintest.ir/guides/run-standalone-test.md): End-to-end flow for a single psychological test on Braintest: list records, authenticate a participant (SMS or instant), submit answers, retrieve results.
- [Run a Cognitive Roadmap with AI Analysis](https://docs.braintest.ir/guides/run-cognitive-roadmap.md): Run a multi-test cognitive roadmap on Braintest: authenticate roles (SMS or instant), complete each test, generate the AI report, and retrieve results.
- [API Error Reference and Troubleshooting](https://docs.braintest.ir/reference/errors.md): Understand HTTP status codes, the JSON error envelope format, and how to resolve common Braintest API errors.
- [Record and Roadmap Status Code Reference](https://docs.braintest.ir/reference/status-codes.md): Learn the status codes for Braintest records and roadmaps, what each state means, and the correct next step for each.
- [Braintest API Rate Limits](https://docs.braintest.ir/reference/rate-limits.md): Braintest API enforces per-minute and per-hour rate limits on every API key. Learn the limits, the 429 response, and how to handle throttling.
- [API Reference Overview](https://docs.braintest.ir/api-reference/overview.md): Braintest API v2 base URL, API-KEY authentication, response envelope format, pagination, and server environments for partner integrations.
- [Test API Key Connection](https://docs.braintest.ir/api-reference/connection/test-connection.md): Verify your Braintest API key is valid by calling GET /auth/connect/. Returns a simple connect: ok response on success, 401 or 403 on failure.
- [List Test Records](https://docs.braintest.ir/api-reference/records/list-records.md): List paginated psychological test records with filters for status, test type, profile gender, and more.
- [Get Test Record Details](https://docs.braintest.ir/api-reference/records/get-record.md): Retrieve a single test record's metadata, including nested test configuration and linked participant profile.
- [Authenticate a Standalone Test Profile](https://docs.braintest.ir/api-reference/records/authenticate-profile.md): Register a participant profile for a standalone test record. Supports both instant authentication and SMS verification depending on the organizer setting.
- [Verify a Standalone Test Profile via SMS](https://docs.braintest.ir/api-reference/records/verify-profile.md): Complete SMS-based standalone test authentication by submitting the draft token and the code the participant received.
- [Get Test Questions](https://docs.braintest.ir/api-reference/records/get-questions.md): Fetch questionnaire content for a test record after profile authentication, returned as structured JSON or HTML.
- [Submit Test Answers](https://docs.braintest.ir/api-reference/records/submit-answers.md): Submit participant answers to score a test record and mark it as finished.
- [Get Test Result (JSON)](https://docs.braintest.ir/api-reference/records/get-result-json.md): Retrieve structured JSON test results for storage, analysis, or custom rendering after a record is finished.
- [Get Test Result (HTML)](https://docs.braintest.ir/api-reference/records/get-result-html.md): Retrieve a rendered HTML report for a finished test record, ready for display, printing, or PDF export.
- [List Cognitive Roadmaps](https://docs.braintest.ir/api-reference/roadmaps/list-roadmaps.md): Retrieve a paginated list of cognitive roadmaps with search and filter support to find multi-test packages by completion state, product type, or participant profile.
- [Get Cognitive Roadmap Details](https://docs.braintest.ir/api-reference/roadmaps/get-roadmap.md): Fetch a full cognitive roadmap instance including required participant roles, nested test records, and product metadata to prepare for administration.
- [Authenticate Roadmap Profiles](https://docs.braintest.ir/api-reference/roadmaps/authenticate-profiles.md): Register all participant profiles for a cognitive roadmap in a single call. Supports both instant authentication and SMS verification depending on the organizer setting.
- [Verify Roadmap Profiles via SMS](https://docs.braintest.ir/api-reference/roadmaps/verify-profiles.md): Complete SMS-based cognitive roadmap authentication by submitting the draft token and the code the participant received.
- [Request AI Roadmap Analysis](https://docs.braintest.ir/api-reference/roadmaps/generate-analysis.md): Queue AI-powered combined analysis for a completed cognitive roadmap. Processing takes 5 to 10 minutes; poll the status endpoint until finished.
- [Get AI Analysis Generation Status](https://docs.braintest.ir/api-reference/roadmaps/get-generation-status.md): Poll the AI generation status endpoint to determine when cognitive roadmap analysis is completed, still processing, or has failed.
- [Get Roadmap Result (JSON)](https://docs.braintest.ir/api-reference/roadmaps/get-result-json.md): Retrieve structured AI analysis JSON for a completed cognitive roadmap, including overview, domain scores, safety flags, and recommendations.
- [Get Roadmap Result (HTML)](https://docs.braintest.ir/api-reference/roadmaps/get-result-html.md): Retrieve a fully rendered HTML cognitive roadmap report for embedding, printing, or PDF generation from a completed multi-test package.