# Create a test

Create an assessment test. Scope: tests:write.

Creates an assessment test. **Scope:** `tests:write`. The creator also persists the test's taxonomy and meters org usage. Non-admins must pass `organizationIds` they have employer-write authority in.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Test name. |
| `type` | string | Yes | Test type (e.g. `multiple_choice`). |
| `description` | string | Yes | Test description. |
| `duration` | integer | Yes | Duration in minutes. |
| `content` | object | Yes | The question structure (shape depends on `type`). |
| `organizationIds` | string[] | For non-admins | Orgs the test belongs to. |
| `targetPersona` / `analysisCategory` / `language` | string | No | Metadata. |
| `primarySkills` / `domains` / `skillLevel` / `tags` | string[] | No | Taxonomy. |

## Example request

```bash
curl -X POST https://app.talent-ray.com/api/v1/tests \
  -H "Authorization: Bearer tr_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "JavaScript Fundamentals", "type": "multiple_choice", "description": "Core JS assessment.", "duration": 30, "organizationIds": ["org_acme"], "content": { "questions": [] } }'
```

## Response

`201 Created` — the created test (same shape as [Get a test](/docs/api/pipeline/tests-get/); the question `content` is not echoed back).

## Status codes

| Status | Meaning |
| --- | --- |
| `201` | Created. |
| `400` | `bad_request` — missing/invalid required fields. |
| `401` | No valid API key. |
| `403` | `insufficient_scope` (missing `tests:write`) or `forbidden` (no write authority in the target org). |
| `429` | Rate limit / usage limit exceeded. |