Skip to main content
For API access, use your API token (obtained from the dashboard under Settings → API Keys) in the Authorization: Bearer header. See Authentication for details.
1

Sign in to Promptster

Sign in at promptster.ai using your organization account. You can sign in via SSO or email.To get your API token, go to Settings → API Keys in the dashboard and copy your token.
2

Create an assessment

Post your task definition. The taskBrief describes what the candidate should build.
curl -X POST https://api.promptster.ai/v1/assessments \
  -H "Authorization: Bearer <your-clerk-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backend API Task",
    "role": "Senior Backend Engineer",
    "taskBrief": "Build a REST endpoint that accepts webhook events and persists them to a database.",
    "timeLimitMinutes": 120,
    "expiresInDays": 7
  }'
The response includes the new assessment’s id. Save it — you’ll need it to generate keys and retrieve sessions.
{
  "assessment": {
    "id": "asmnt_01j...",
    "title": "Backend API Task",
    "role": "Senior Backend Engineer",
    "timeLimitMinutes": 120,
    "expiresInDays": 7
  }
}
You can generate up to 50 candidate keys per assessment. Set expiresInDays to control how long a key remains valid after generation — after expiry, the key cannot be redeemed.
3

Generate candidate keys

Generate one key per candidate. If you include candidateEmails, Promptster sends invite emails automatically.
curl -X POST https://api.promptster.ai/v1/assessments/<assessment-id>/keys \
  -H "Authorization: Bearer <your-clerk-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 3,
    "candidateEmails": ["alice@example.com", "bob@example.com", "carol@example.com"],
    "candidateNames": ["Alice", "Bob", "Carol"],
    "orgName": "Acme Corp"
  }'
The response contains the generated keys. Each key has the format PST-XXXX-XXXX.
{
  "keys": [
    { "id": "ck_01j...", "key": "PST-A3BZ-Q7NP", "candidateEmail": "alice@example.com", "expiresAt": "2026-04-14T..." },
    { "id": "ck_01j...", "key": "PST-R2CW-H5MK", "candidateEmail": "bob@example.com",   "expiresAt": "2026-04-14T..." },
    { "id": "ck_01j...", "key": "PST-T8DV-J4XL", "candidateEmail": "carol@example.com", "expiresAt": "2026-04-14T..." }
  ]
}
candidateEmails and candidateNames are optional and positional — the first email is paired with the first name. If you omit them, keys are generated without any candidate association and no email is sent.
4

Candidates complete the assessment

Share the PST-XXXX-XXXX key with each candidate. They install the Promptster CLI and run:
promptster start PST-XXXX-XXXX
This configures Claude Code or Cursor to capture session telemetry automatically. The candidate works normally and runs promptster done to submit when finished.
5

List sessions for your assessment

Once a candidate submits, their session appears in the list.
curl "https://api.promptster.ai/v1/sessions?assessmentId=<assessment-id>" \
  -H "Authorization: Bearer <your-clerk-token>"
The response is a paginated list of sessions. Each session includes summary fields like eventCount, decisionFlagCount, and aiAttributionPct.
{
  "sessions": [
    {
      "id": "sess_01j...",
      "startedAt": "2026-04-07T10:00:00Z",
      "endedAt": "2026-04-07T11:47:23Z",
      "eventCount": 342,
      "decisionFlagCount": 4,
      "aiAttributionPct": 0.71
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
6

Review the session timeline

Fetch the full chronological event log for a session. The timeline returns events in order, paginated by limit (max 2000 per request).
curl "https://api.promptster.ai/v1/sessions/<session-id>/timeline" \
  -H "Authorization: Bearer <your-clerk-token>"
Use the after cursor for subsequent pages:
curl "https://api.promptster.ai/v1/sessions/<session-id>/timeline?after=<last-event-id>" \
  -H "Authorization: Bearer <your-clerk-token>"
The response includes a hasMore flag indicating whether additional pages exist.
7

Review decisions

Fetch the architecture decisions the candidate captured during the session.
curl "https://api.promptster.ai/v1/sessions/<session-id>/decisions" \
  -H "Authorization: Bearer <your-clerk-token>"
Each decision is a decision_event timeline row with the candidate’s choice, rationale, and tradeoffs.
{
  "decisions": [
    {
      "id": "evt_01j...",
      "kind": "decision_event",
      "ts": "2026-04-07T10:22:41Z",
      "data": {
        "title": "Use a message queue for webhook ingestion",
        "chosenOption": "HTTP push queue",
        "rationale": "Avoids polling, no extra infrastructure required. Simpler ops footprint.",
        "impactScore": 4
      }
    }
  ]
}

​
Next steps

Session review

Understand the full session data model and how to interpret signals.

Cohort stats

Compare a candidate’s metrics against the rest of the cohort.

Manage assessments

Full reference for assessment and key management.

API reference

Complete API reference for all reviewer endpoints.