Quickstart

Two minutes to your first response. You’ll use a test key, which is served from a fixed dataset — nothing real is read or written, so you can’t break anything.

Mint a test key

In the dashboard, open Settings → API keys, click Create API key, and choose:

Environment — Test
Scopes — read and write (write lets you try the create endpoints)
Expiry — whatever suits you; keys can be revoked at any time

The key is shown once. Copy it before closing the dialog.

export DOTPORTION_TEST_KEY="sk_test_..."

Make a request

curl https://app.dotportion.com/api/v1/challenges \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY"

You’ll get three sample challenges wrapped in the standard envelope:

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "slug": "lru-cache",
      "name": "LRU Cache",
      "difficulty": "easy",
      "is_platform": true,
      "is_multi_task": false
    }
  ],
  "meta": { "request_id": "req_...", "page": 1, "page_size": 20, "total": 3, "has_more": false }
}

Every response carries meta.request_id. Log it — with it we can find your exact call; without it, a 500 is a needle in a haystack.

Run the loop

Create an assessment, invite a candidate, then read a report. All simulated: the writes return realistic objects and persist nothing.

curl -X POST https://app.dotportion.com/api/v1/assessments \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "00000000-0000-4000-8000-000000000001",
    "name": "Backend hire — Q1"
  }'

curl -X POST https://app.dotportion.com/api/v1/assessments/00000000-0000-4000-8000-000000000011/invitations \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidate_email": "ada@example.com", "candidate_name": "Ada Lovelace" }'

curl https://app.dotportion.com/api/v1/submissions/00000000-0000-4000-8000-000000000031/report \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY"

Those ids aren’t placeholders — they’re the fixed sandbox ids, safe to hard-code in your own tests. The full list is in Test mode.

Handle the failures too

Point your error handling at real responses rather than guessing. Two documented inputs make the awkward cases reproducible:

curl https://app.dotportion.com/api/v1/assessments/00000000-0000-4000-8000-0000000000ff \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY"

curl -X POST https://app.dotportion.com/api/v1/assessments/00000000-0000-4000-8000-000000000011/invitations \
  -H "Authorization: Bearer $DOTPORTION_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "candidate_email": "limit@example.com" }'

The rest happen naturally — send an invalid body for 400, use a read-only key on a write for 403. See Errors.

Go live

Mint a second key with Environment: Live and the narrowest scopes that do the job. Nothing else in your code changes — same URLs, same shapes.

A live key reads and writes your real data, and inviting a candidate consumes plan quota and sends them an email. Keep the test key in CI.

Authentication

Scopes, expiry, rotation, and what a leaked key can do.

Responses & pagination

The envelope, and how to walk a cursor to the end.

Understanding reports

Read a ship score and verdict without over-reading them.

API reference

Try every endpoint in the playground.

Getting started

Core concepts

Hiring reports

Your workspace

Help

Next

Authentication

Responses & pagination

Understanding reports

API reference

​Next

Authentication

Responses & pagination

Understanding reports

API reference

Next