Create a practice test

Writes a practice test from study sets and notes, as the app's New test dialog does. The test starts as generating: poll GET /jobs/{jobId} or GET /tests/{testId} until its status is ready. Counts as an AI use. Send the same requestId again to retry safely: it returns the same test. A refused start leaves no test behind.

Required scopes: tests:generate

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

A client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.

Match^[\x21-\x7E]{1,255}$

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

requestId*string

A uuid you mint for this start. It becomes the job id. Sending it again with the same sets, notes, kinds, length, timerSecs and modelTier returns the original test and is not counted twice. name is not compared, so a replay under another name still returns the original test with its original name. Any other change under a used requestId is 409 idempotency_conflict.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

name*string

The test's name, 1-120 characters.

Length1 <= length <= 120

sourceSetIds?array<>

Study sets to write questions from, up to 10.

Itemsitems <= 10

Default[]

sourceNoteIds?array<>

Notes to write questions from, up to 10. Name at least one set or note, and they must have text.

Itemsitems <= 10

Default[]

kinds*array<>

The kinds of question to ask, at least one.

Items1 <= items

length*integer

How many questions, 1-50.

Range1 <= value <= 50

timerSecs?|

A time limit in seconds, 60-7200, counted from the start of each attempt. Null or omitted for no limit.

Defaultnull

modelTier?string

swift, scholar (the default) or sage. sage needs a paid plan; a free user gets 400 with details.reason premium-only.

Value in

"swift"
"scholar"
"sage"

Response Body

`application/json`

curl -X POST "https://example.com/tests" \  -H "Content-Type: application/json" \  -d '{    "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",    "name": "string",    "kinds": [      "MCQ"    ],    "length": 1  }'

{  "data": {    "testId": "6e5d4c3b-2a19-4f08-8e7d-6c5b4a392817",    "jobId": "7d6c5b4a-3f2e-4d1c-8b0a-9f8e7d6c5b4a"  }}

Create a practice test

Authorization

Header Parameters

Request Body

Response Body

202application/json

400application/json

401application/json

402application/json

403application/json

404application/json

405application/json

409application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`