API reference

Every endpoint under /v1: authentication, money, idempotency, the error envelope, and the complete request and response for each route.

Runs on your server. The guide is Report the score from your server.

The contract

Base URL

https://api.withchallenge.com/v1

Local development is http://localhost:4837/v1. There is no separate sandbox host: the key decides the environment. See Sandbox.

Anything under /v1 is stable. Fields are added, never removed or retyped, without a new version. Routes under /api carry no such promise; they belong to Challenge's own portals and the island, and they are free to change.

Authentication

Every request carries an X-API-Key header. sk_test_... is sandbox, sk_live_... is production.

The key resolves to exactly one program, so program is not a parameter on any route. That is what removes the class of tenancy bug where a request reads across partners: there is no "which of this developer's programs did they mean" question to answer wrong.

Every key failure is one 401 with the code unauthorized. A missing header, a malformed key, an unknown key, a test key used where a live one was expected, a live key on a program that is not yet approved, a suspended or closed program, and an account scheduled for deletion all answer identically. Distinguishing them would tell an attacker which half of a guess was right. See Programs and keys.

Money is a decimal string

Every amount in /v1 is a string: "25.00", never 25.0. Binary floats cannot represent cents exactly, and a partner parsing 25.00 as 24.999999 would be a bug Challenge owned. Parse them with a decimal type, not with parseFloat.

Scores and thresholds are JSON numbers, because they are measurements rather than money.

Webhook payloads are the one exception in the other direction: their amounts are JSON numbers. See Webhook events.

The error envelope

code is a closed, versioned set. Branch on the code, never on the message. Wording is not part of the contract and may change at any time. details is present only on some validation failures.

The full catalog, with a cause and a fix for each code, is Errors.

Idempotency

Idempotency-Key is required on every endpoint that moves money: POST /v1/attempts, POST /v1/attempts/{id}/outcome and POST /v1/challenges/{id}/distribution. Use a fresh value per logical operation, typically a UUID, up to 255 characters.

Records are retained for 24 hours, and the same key on a different endpoint is a different record. Only 2xx responses are stored: replaying a 500 would turn a transient failure into a permanent one.

This sits on top of the ledger's own idempotency. The ledger guarantees a repeated key moves no money, which protects the balance but not the caller: a retried request would still re-run the side effects around the transfer and hand back a different body. Every webhook retries, timeouts included, so "charged once but told twice" is a real state your code has to survive.

Cross-program resources answer not_found

A challenge, attempt, round or integration that belongs to another program answers 404 not_found, not 403. A 403 would confirm the resource exists. Tenancy is applied inside the query rather than checked after it, so there is no path where the wrong row is read and then rejected.

Rate limits

/v1 allows 300 requests per minute per API key. Over the limit the answer is 429 with Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers. The 429 body is the limiter's own shape rather than the error envelope:

The retired client-reporting route

POST /api/attempts/{id}/outcome was how a browser used to report a score. It is mounted, bare, and answers 410:

410 rather than 404 because the resource is not missing, and rather than 403 because the caller is not unwelcome: it is retired. It carries no auth and no idempotency middleware, so a stale bundle in someone's cache costs nothing and gets an explanation instead of what it would read as an outage. Challenge.reportScore() throws the same code in the browser. See The trust model.

Challenges

The guide is Challenges.

GET /v1/challenges

The Challenges this player may attempt right now. Safe to render straight into a menu: everything returned is something POST /v1/attempts will accept for that player.

The ramp object carries active (always true when present), fullPrize as a decimal string, and attemptsSeen against attemptsRequired. The calibration object carries collected against required and playersCollected against playersRequired. See Calibration.

Three things are deliberately absent from the list:

• Challenges this player has already claimed. A Challenge pays one prize per player for life, so a claimed one cannot be attempted again and listing it would make you carry that rule.
• Locked rungs. A rung whose parent this player has not claimed is not attemptable yet. The island lists them, marked locked, because a locked rung is what a ladder sells; your own page is not Challenge's to put a "you cannot have this" card on. See The Challenge ladder.
• Anything the player is ineligible for, by jurisdiction, age, verification level or self-exclusion.

An unknown player_ref is not an error. Someone who has never played has claimed nothing, which claims none and locks every rung, and both of those are the true answer.

calibration_players, min_calibration_players and ramp_completed_at exist on the row and are stripped from the response. The first two are reported inside the calibration object instead; the third is internal bookkeeping that the ramp object says better.

Errors: 400 invalid_request when player_ref is missing, 401 unauthorized.

POST /v1/challenges/{id}/distribution

Skip the cold start by supplying percentiles from your own history. Requires Idempotency-Key.

You send percentiles rather than rows: that is all a threshold needs, it carries no personal data, and it comes out of one SQL query on your side.

Percentiles must rise from p5 to p95. Percentiles that do not ascend are not percentiles, and accepting them would interpolate nonsense.

201. The Challenge is live immediately, at a prize capped to 20% of your tier ceiling until the drift monitor confirms the claim against real paid attempts. Supplying the distribution means setting the threshold, which sets the pass rate, which sets Challenge's expected cost per attempt, so the cap is what makes an unverified claim safe to act on.

Errors: 400 invalid_request for a bad or non-ascending distribution, a sample_size under 500, a Challenge that is not calibrating (a live one would move the bar under players mid-flight; a suspended one is not reinstated this way), a Challenge that is a rung of a ladder (a rung's bar is measured from the players who claimed the rung below it and cannot be supplied), and for a challenge id this program does not own. 401 unauthorized. 409 on idempotency conflicts.

Players

The guide is Server-created attempts.

POST /v1/players

Link one of your player identifiers to an existing Challenge account. Without this, nothing can create the row that player_ref resolves through, so no server-created attempt can be made.

201. No Idempotency-Key: the link upserts on the program and the ref, so repeating the call is naturally safe and returns the same answer. Idempotency belongs where repetition is unsafe, not on every write.

There is no auto-provisioning on first attempt, deliberately. A player_ref is a string you chose, and treating it as authority to create a Challenge account would mint accounts that hold money with no email, no age check and no consent. The player signs up with Challenge; you link the account they already have.

Errors: 400 invalid_request when either field is missing. 404 not_found when no Challenge account matches the email, phrased as a plain absence rather than "no such user": confirming which emails have accounts would let any partner enumerate Challenge's players. 401 unauthorized.

Attempts

The guides are Start a paid attempt and Report the score from your server.

POST /v1/attempts

Create an attempt and charge the fee in the same transaction. Requires Idempotency-Key.

Send exactly one parent. Sending both, or neither, is 400 invalid_request. The two are not interchangeable: one is judged against a frozen bar for a fixed prize, the other buys a place in a round that pays by rank. A request naming both has not said which deal it wants, and picking one would be picking how a player's money is used. The same rule is enforced by a check constraint on the table.

Entering a tournament round is the same call with the other parent:

201 in both cases. Exactly one of challenge_id and tournament_round_id is ever non-null, on this response and on every later read of the attempt, and which one it is says whether the attempt is playing for a fixed prize or for a rank.

A replay returns the original body with Idempotency-Replayed: true. It charges nothing further, and on a tournament round it consumes no second slot against the round's attempt cap.

Errors:

No 409 charges anything.

POST /v1/attempts/{attempt_id}/outcome

Report what the player achieved. Requires Idempotency-Key.

Note what this endpoint does not accept: whether the player won. That is Challenge's determination, applied against the threshold frozen onto the attempt at its creation. You supply a measurement; Challenge applies the standard. It is also why generous reporting cannot inflate payouts.

A tournament attempt settles through this same endpoint and gets a different shape, because there is no bar and no per-attempt prize on a rank table:

met_threshold: false here is not a loss. It is the honest answer to a question that does not apply: the score has been entered on the round's board, and the round pays by rank at its close. award stays null because a tournament pays through settlement, not through the outcome. receipt_id is written exactly as it is on a Challenge.

Errors:

On attempt.settled, re-fetch rather than reconstruct: call GET /v1/attempts/{id} and trust that.

GET /v1/attempts/{attempt_id}

Read one attempt and its outcome. The authoritative answer for what an attempt did.

An attempt with no outcome after an hour expires and the fee is refunded, which is status: "expired" here and an attempt.refunded webhook.

Errors: 401 unauthorized, 404 not_found for an unknown attempt or one belonging to another program.

Tournaments

The guide is Tournaments.

GET /v1/tournaments

This program's tournaments, each with the round it is running.

There is no player_ref here, and the absence is deliberate. A Challenge list is filtered per player because eligibility decides what may be offered. A tournament round is one public board, identical for everyone, so asking for a player identifier to return a list that does not depend on it would be collecting an identifier Challenge has no use for.

The tournament object:

current_round semantics. It is the open round when there is one, and otherwise the most recent round there has been, so a tournament between rounds still renders with the board its last round finished on. It is null only before the first round has ever spawned. Read current_round.id to enter, and check current_round.status first: only an open round accepts entries.

The round object, which appears here and on the leaderboard response:

funding is always "house": Challenge funds a fixed purse, announced before the round opened and identical at any field size. pool_amount and rollover_in are legacy fields from the retired pooled model. They are always "0.00" and are kept only so parsers written against the older shape do not break. Do not compute a prize from them; purse_amount and purse_table are the numbers that pay.

min_entrants is a condition of the contest, not an internal threshold, and is worth showing to players: below it at close, the round cancels and every entry is refunded in full. That refund is how a fixed purse is underwritten.

settling is the intermediate status between open and settled: the round has closed and standings are being computed. A round in settling accepts no entries and its final_rank fields are not yet written.

Errors: 401 unauthorized.

GET /v1/tournaments/rounds/{round_id}/leaderboard

The rank table for one round. Live standings while it is open, the final table once it has settled.

The board is enter to see. Ranks and scores are returned only for a player who has paid for at least one attempt in this round, so player_ref says who you are rendering for. Name a player who has entered and you get the board below. Send no player_ref, an unknown one, or one who has not entered this round, and you get the masked shape instead: a 200 with locked: true and no data. A valid API key is not a player, so a call with no player_ref is always masked.

A live board is a neighborhood, not the whole table. While the round is running, data carries only the named player's own row with one rank above and one below: the race they are actually in. There is no always-visible top; the leading rows come into view only as the player climbs next to them. A player who has paid but not yet scored gets an empty data array. scored_players on the response says how long the full table is, so "rank 6 of 41" is renderable without the rest of it, and the rank numbers say where the visible rows sit. Once the round is settled or cancelled, data is the complete final table. Render what you receive: the rows are the board that player is allowed to see, and padding it out from your own records would defeat the point of the cut.

Only players who have posted a score appear.

Ties break on play, then on the clock: the better score, then the better best_tiebreak on the tournament's declared tiebreak metric (null ranks worse than any value), then the earlier best_score_at, then the entry id. The tiebreak metric is what keeps a round alive on a metric with a reachable best: a player who matches the leading score wins by beating their tiebreak, right now, in the game, instead of having lost to an earlier post. The timestamp and the entry id are last-resort determinism, so two computations of the same board always agree. best_tiebreak is the tiebreak of the run that holds best_score: one performance, ranked as a pair. On tournaments predating the tiebreak rule every best_tiebreak is null and ties fall to the clock as before.

Before settlement, final_rank is null, payout_amount is null and payout_status is none. That combination says the table is not final yet. Null is not zero, and this field never confuses the two: null means no decision has been made, "0.00" would mean a decision was made and it pays nothing.

After settlement, payout_status is paid for a rank that has been paid, held for one behind an open investigation, and refunded for every entrant of a round cancelled for too small a field.

The masked shape, returned when the caller has not named a player who has entered this round:

There is no data array on a masked response. An empty array would be a claim that nobody has scored, and this response is not making one; scored_players is the honest count.

It is a 200 rather than a refusal on purpose. Not having entered yet is the ordinary state of a player who has not entered yet, so the response keeps its shape and every field on it is something you would render on the pre-entry screen. Branch on locked, not on a status code.

Live scores were visible to any caller before 26 August 2026 and are not any more. Under a house-funded purse what underwrites the prize is turnout, so a player deterred by the board does not shrink the purse, they raise the chance the round cancels and refunds. Everything the round promises stays visible; the field's scores are behind the fee.

Errors: 401 unauthorized. 404 not_found for an unknown round and for a round belonging to another program: tenancy is applied to the query, so another partner's round is absent rather than forbidden. Tenancy is checked before the board rule, so another partner's round is not_found rather than masked.

Integrations

An integration is how Challenge and your systems exchange outcomes. Creating one from the API is what makes the descriptor architecture usable without hand-written SQL.

Two things happen at save time that cannot happen later. The descriptor is validated, so a mistyped path is caught while you configure rather than when your first live outcome silently fails to map and a player goes unpaid. And a pull endpoint is checked for safety at save time as well as at fetch time, so an internal URL cannot sit in the database waiting for the poller.

All five routes answer only four codes: invalid_request (400), unauthorized (401), not_found (404) and internal_error (500). None of them takes an Idempotency-Key.

POST /v1/integrations

201. The secret is 64 hexadecimal characters. It is shown exactly once, in this response, and is never returned again by any route. A secret readable on demand is a secret that leaks through every subsequent bug: a logged response, an over-broad admin view, a support screenshot. Store it now.

Only push_webhook gets a secret, along with webhook_url and signing_instructions. Generating one for every transport would create secrets nobody uses and everyone has to protect.

Every integration is created draft. One that went live on creation would start accepting money-moving callbacks before anyone had reviewed it.

X-Challenge-Signature is the header you send Challenge on a push webhook. It is not the same as X-Webhook-Signature, which is the header Challenge sends you on an outbound event. See Webhooks.

Errors: 400 invalid_request for an unknown transport, a descriptor that fails validation, a pull_interval_seconds under 30 or not an integer, or a pull endpoint that is not a safe URL.

GET /v1/integrations

Every integration on this program, newest first.

has_signing_secret is the only thing said about the secret anywhere after creation.

PATCH /v1/integrations/{id}

The response is the same public view as the list, with the update applied. Only the fields you send are changed.

Errors: 400 invalid_request for a status outside the three, a descriptor that fails validation, a bad interval, an unsafe pull endpoint, and for activating a push_webhook that has no signing secret. 404 not_found for an unknown id or one on another program.

POST /v1/integrations/{id}/rotate-secret

Issue a new signing secret while the old one keeps verifying.

The rotation overlaps on purpose. A hard cutover drops every delivery already in flight, which is the reason partners avoid rotating at all, and a secret nobody rotates is worse than an awkward rotation. Deploy the new secret, confirm traffic verifies against it, then retire the old one.

This is the second and last time a secret is returned, and it is a different secret from the first.

Errors: 400 invalid_request when the integration is not a push_webhook, since only those have a signing secret. 404 not_found for an unknown id or one on another program.

DELETE /v1/integrations/{id}/previous-secret

Retire the old secret. After this, only the current one verifies.

The response is the public view. Safe to call when there is no previous secret; it is a no-op.

Errors: 404 not_found for an unknown id or one on another program.

What is not in this API

• There is no POST /v1/challenges. Creating a Challenge is a pricing decision Challenge participates in, made in the Developer Portal. See Challenges.
• There is no endpoint that sets a threshold, a fee or a prize. The bar is measured, and the fee and prize follow from it. See Calibration.
• There is no endpoint that reports a win. The outcome call accepts score, never won.
• There is no way to read a signing secret after the response that created or rotated it.
• There is no self-serve live-key rotation. Live keys are issued at approval. Test keys can be regenerated from the Developer Portal.

Related

• Report the score from your server: the guide this page is the reference for
• Server-created attempts: the player_ref path for games with no browser client
• Webhook events: every event Challenge emits, with payloads
• Errors: every code, with cause and fix
• Programs and keys: what each key may touch

Source: https://www.withchallenge.com/docs/api.md Docs index for AI agents: https://www.withchallenge.com/llms.txt