Create Assessment

POST

assessments

curl -X POST https://api.promptster.ai/v1/assessments \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "anthropicKeyMode": "byok",
    "anthropicKeyId": "11111111-2222-3333-4444-555555555555",
    "openaiKeyMode": "byok",
    "openaiKeyId": "66666666-7777-8888-9999-000000000000"
  }'

{
  "assessment": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123",
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook that causes the counter to show incorrect values after rapid clicks.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "issueId": null,
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "expiresInDays": 7,
    "createdAt": "2026-04-07T10:30:00.000Z"
  }
}

Create an assessment that defines the coding task candidates will complete. You can link it to an OSS issue from the Promptster problem library, or provide your own task brief and repo URL.

Authentication

Requires an org API key with an active subscription.

Authorization: Bearer psk_live_...

string

required

The assessment title shown to candidates and in the dashboard.

string

required

The role this assessment is for (e.g. “Senior Frontend Engineer”).

string

Markdown description of the task. Required if issueId is not provided. Auto-populated from the issue if omitted.

string

URL of the repository candidates will work in. Must be a valid URL.

string

ID of an OSS issue from the Promptster problem library. When provided, the task brief is auto-populated from the issue.

integer

Time limit for the assessment in minutes. Must be a positive integer.

integer

default:"7"

Number of days before candidate keys expire. Must be a positive integer.

number

Maximum token spend allowed per candidate in USD. Must be positive and at most 1000. Claude Code and Codex draw from this single shared per-candidate budget — allowing both tools does not double it.

string[]

default:"[\"claude\",\"codex\",\"cursor\"]"

Which AI coding tools the candidate may use. One or more of:

claude — Claude Code. Requires an org Anthropic key.
codex — Codex CLI. Requires an org OpenAI key.
cursor — Cursor. The candidate brings their own Cursor subscription, so no org key is needed.

If you omit this field, it is auto-derived from the provider keys your org has configured: claude is included if a usable Anthropic key resolves, codex if a usable OpenAI key resolves, and cursor is always included.If you set it explicitly, your org must have a usable key for each selected tool’s provider (claude → Anthropic, codex → OpenAI; cursor needs none), otherwise creation fails with 400 { "code": "byok_required" }.

string

default:"org_default"

Which Anthropic key the assessment uses when claude is allowed. org_default uses your org’s default Anthropic key; byok uses the specific key named by anthropicKeyId.

string

ID (UUID) of the Anthropic key to use when anthropicKeyMode is byok. Discover key IDs via List Provider Keys. An invalid or unknown ID fails with 400 { "code": "byok_key_invalid" }.

string

default:"org_default"

Which OpenAI key the assessment uses when codex is allowed. org_default uses your org’s default OpenAI key; byok uses the specific key named by openaiKeyId.

string

ID (UUID) of the OpenAI key to use when openaiKeyMode is byok. Discover key IDs via List Provider Keys. An invalid or unknown ID fails with 400 { "code": "byok_key_invalid" }.

To select a specific provider key, first call List Provider Keys to find its id, then pass it as anthropicKeyId or openaiKeyId.

object

The created assessment object.

Show properties

string

Unique assessment ID (UUID).

string

Your organization ID.

string

Assessment title.

string

Target role.

string

Task description.

string | null

Repository URL.

string | null

Linked OSS issue ID.

integer | null

Time limit in minutes.

number | null

Token budget in USD.

string[]

The resolved set of tools the candidate may use (claude, codex, cursor).

integer

Key expiry period in days.

string

ISO 8601 timestamp.

{
  "assessment": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123",
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook that causes the counter to show incorrect values after rapid clicks.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "issueId": null,
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "expiresInDays": 7,
    "createdAt": "2026-04-07T10:30:00.000Z"
  }
}

curl -X POST https://api.promptster.ai/v1/assessments \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "anthropicKeyMode": "byok",
    "anthropicKeyId": "11111111-2222-3333-4444-555555555555",
    "openaiKeyMode": "byok",
    "openaiKeyId": "66666666-7777-8888-9999-000000000000"
  }'

curl -X POST https://api.promptster.ai/v1/assessments \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "anthropicKeyMode": "byok",
    "anthropicKeyId": "11111111-2222-3333-4444-555555555555",
    "openaiKeyMode": "byok",
    "openaiKeyId": "66666666-7777-8888-9999-000000000000"
  }'

{
  "assessment": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orgId": "org_2abc123",
    "title": "React State Management Bug Fix",
    "role": "Senior Frontend Engineer",
    "taskBrief": "Fix the stale closure bug in the useEffect hook that causes the counter to show incorrect values after rapid clicks.",
    "repoUrl": "https://github.com/acme/frontend-challenge",
    "issueId": null,
    "timeLimitMinutes": 60,
    "tokenBudgetUsd": 25.0,
    "allowedTools": ["claude", "codex", "cursor"],
    "expiresInDays": 7,
    "createdAt": "2026-04-07T10:30:00.000Z"
  }
}

Get Started

Understanding Sessions

Guides

API Reference

Assessments

Keys

Sessions

Candidates

Analytics

Problem Library

Hooks

Branding

Webhooks

Resources

Authentication

​Authentication

Authentication