Generate Candidate Keys

POST

assessments

:id

keys

curl -X POST https://api.promptster.ai/v1/assessments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/keys \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 1,
    "candidateEmails": ["[email protected]"],
    "candidateNames": ["Jane Smith"],
    "orgName": "Acme Corp"
  }'

{
  "keys": [
    {
      "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "key": "PST-ABCD-1234",
      "assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_2abc123",
      "candidateEmail": "[email protected]",
      "candidateName": "Jane Smith",
      "status": "pending",
      "sessionId": null,
      "expiresAt": "2026-04-14T10:30:00.000Z",
      "redeemedAt": null,
      "completedAt": null,
      "createdAt": "2026-04-07T10:30:00.000Z"
    }
  ]
}

Generates one or more candidate keys (PST-XXXX-XXXX) for an assessment. Each key is a unique invite that a candidate uses to start their session via the Promptster CLI. When candidateEmails are provided, invite emails are sent automatically via Loops with instructions on how to get started.

Authentication

Requires an org API key with an active subscription.

Authorization: Bearer psk_live_...

string

required

The assessment ID (UUID).

integer

required

Number of keys to generate. Must be between 1 and 50.

string[]

Email addresses for each candidate. When provided, invite emails are sent automatically. Array length should match count.

string[]

Display names for each candidate. Array length should match count.

string

Your organization name, included in the invite email for context.

array

List of generated candidate key objects.

Show properties

string

Unique key record ID (UUID).

string

The candidate key (e.g. PST-ABCD-1234).

string | null

Candidate’s email if provided.

string | null

Candidate’s name if provided.

string

Key status: pending, active, completed, or expired.

string

ISO 8601 expiration timestamp.

string

ISO 8601 creation timestamp.

{
  "keys": [
    {
      "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "key": "PST-ABCD-1234",
      "assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_2abc123",
      "candidateEmail": "[email protected]",
      "candidateName": "Jane Smith",
      "status": "pending",
      "sessionId": null,
      "expiresAt": "2026-04-14T10:30:00.000Z",
      "redeemedAt": null,
      "completedAt": null,
      "createdAt": "2026-04-07T10:30:00.000Z"
    }
  ]
}

curl -X POST https://api.promptster.ai/v1/assessments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/keys \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 1,
    "candidateEmails": ["[email protected]"],
    "candidateNames": ["Jane Smith"],
    "orgName": "Acme Corp"
  }'

curl -X POST https://api.promptster.ai/v1/assessments/a1b2c3d4-e5f6-7890-abcd-ef1234567890/keys \
  -H "Authorization: Bearer psk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 1,
    "candidateEmails": ["[email protected]"],
    "candidateNames": ["Jane Smith"],
    "orgName": "Acme Corp"
  }'

{
  "keys": [
    {
      "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "key": "PST-ABCD-1234",
      "assessmentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_2abc123",
      "candidateEmail": "[email protected]",
      "candidateName": "Jane Smith",
      "status": "pending",
      "sessionId": null,
      "expiresAt": "2026-04-14T10:30:00.000Z",
      "redeemedAt": null,
      "completedAt": null,
      "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

Generate Candidate Keys

Authentication

​Authentication

Authentication