API keys

1. Get started

1. Sign in, register your team and accept the current Challenge Rules and Terms of Use.
2. Your captain creates a key on this page; members of partner teams each create their own personal keys. Copy the secret when it appears; it is only shown once.
3. Set the environment variables below. Replace YOUR_API_KEY with your key. Store real keys in your environment or secret manager.
4. Send Authorization: Bearer YOUR_API_KEY on authenticated requests. Public endpoints do not need a key.

export VE_API_BASE="https://api.virtualembryo.ai"
export VE_CHALLENGE_API_KEY="YOUR_API_KEY"

# Check availability and accepted targets (no key needed).
curl --fail-with-body -sS "$VE_API_BASE/challenge/phase"
curl --fail-with-body -sS "$VE_API_BASE/challenge/boards"

# Check your team's quota.
curl --fail-with-body -sS "$VE_API_BASE/challenge/integration/quota" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

The commands use cURL and local files. Do not set Content-Type manually for an upload: cURL supplies the multipart boundary.

2. Available endpoints

Public · no authentication

Team API · Bearer key required

In evidence paths, {id} is the prediction’s submission ID. A key can only access its own team’s submissions. Keys include submission and quota scopes; Agent Team keys also include evidence scopes. Read-only partner keys omit upload permissions.

Create, list and revoke keys on this page. The management endpoints POST/GET /challenge/api-keys and POST /challenge/api-keys/{key_id}/revoke require your normal sign-in: captain access for ordinary teams, or personal access for partner-team members. API keys cannot manage keys, teams, accounts or document acceptance.

Download data

Enable Allow data downloads when creating your key to grant data:read. Existing keys keep their original permissions. Your script or platform can list released training files and request a direct download link for you.

# Create a personal key with Allow data downloads enabled.
curl --fail-with-body -sS "$VE_API_BASE/challenge/data/manifest" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

# Use an exact key returned by the manifest.
curl --fail-with-body -sS --get "$VE_API_BASE/challenge/data/link" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  --data-urlencode "key=T2/E6.75.h5ad"

# Open the returned url directly; do not send your API key to storage.

The link response includes url, expires_in (at most 900 seconds), expires_at and file metadata. A normal browser link starts the download from VE storage; no VE browser sign-in is needed at that step. Request a fresh URL after expiry and keep signed URLs private.

Each request checks current membership and Rules/Terms acceptance. Downloads do not consume submission allowance. Leaving a team or losing eligibility blocks new links; a link already issued may work until it expires. Only released training inputs are available.

Platforms must use each participant's personal key, not a partner service credential. HTTP 409 means current agreements need acceptance in VE; HTTP 503 means the release or storage is unavailable. This download integration does not authorize redistribution or hosting copies of the data.

3. Check and upload a prediction

Send a multipart form to POST /challenge/submissions. The server chooses the phase’s validation or test split; query GET /challenge/boards for the targets currently available.

For Agent Teams, provide both agent declaration fields on official uploads. Human Teams do not need them. For T3, set task=T3 and use the task’s prediction file. See the task definitions for file contents and task-specific shapes.

First run a format check

Set format_only=true and omit Idempotency-Key. The response includes ok, problems and format_only. No submission is created and no official attempt is spent. Passing this preliminary check does not guarantee scorer acceptance.

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -F "task=T1" \
  -F "format_only=true" \
  -F "[email protected]"

Then submit for scoring

# Change this ID for a new prediction; keep it unchanged for retries.
export VE_REQUEST_ID="prediction-001"

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -H "Idempotency-Key: $VE_REQUEST_ID" \
  -F "task=T1" \
  -F "model=My prediction method" \
  -F "[email protected]"

Save the returned id. The upload response also includes status, task, bundle_key, phase, bytes, sha256, problems and used_credit. A rejected prediction can still return HTTP 200: inspect status and problems, not only the HTTP code.

T2: specify the setting and mode

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -H "Idempotency-Key: heart-prediction-001" \
  -F "task=T2" \
  -F "setting=heart" \
  -F "mode=extrap" \
  -F "model=My prediction method" \
  -F "file=@heart_prediction.h5ad"

For the embryo interpolation target, use setting=embryo and mode=interp with its matching file. Official prediction uploads are capped at 1,200 MiB per file; format checks use the same file-size limit.

4. Follow status and read scores

# Replace this with the id returned by POST /challenge/submissions.
export VE_SUBMISSION_ID="SUBMISSION_ID"

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions/$VE_SUBMISSION_ID" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

Poll the detail endpoint every 15–30 seconds, with slower polling during outages. The response includes the following fields; this queued example is illustrative.

{
  "id": "SUBMISSION_ID",
  "task": "T1",
  "status": "queued",
  "bundle_key": "T1:val",
  "sha256": "SERVER_COMPUTED_SHA256",
  "headline": null,
  "metrics": null,
  "rank": null,
  "board_size": null,
  "reject_reason": null,
  "scored_at": null,
  "shows_scores": false
}

cancelled

Terminated by withdrawal or eligibility changes. This submission cannot restart and its allowance is not refunded.

eligibility_review

Historical eligibility needs organiser review; not queued for scoring.

awaiting_evidence

Agent evidence is still required. Attach it to this submission ID.

queued

Accepted and waiting for the scoring worker.

scoring

The scoring worker is processing the prediction.

scored

Scoring finished. Read headline and metrics when shows_scores is true.

rejected

The prediction was refused. Read reject_reason (or problems in the upload response).

When scoring is finished and shows_scores=true, headline is the submission’s headline score and metrics contains its detailed metrics. rank and board_size describe your team’s standing on that board using its best score, rather than this file’s position among all uploads. These fields can be null before scoring or when scores are not published in the current phase.

The detail response includes sha256, the server-computed SHA-256 of the exact uploaded file bytes (64 lowercase hexadecimal characters). Partner submission details also include the stable member_id of the submitting member. The digest remains available after archival or re-scoring; it does not imply that a pending or rejected file has received a score.

History returns registered and submissions, with up to the latest 200 entries. Check reject_reason for rejections and reclaimed_at in history for prediction files that are no longer retained.

5. Read public leaderboards

Leaderboard requests need no key. Use task=T1, T2 or T3; optional board is a key from /challenge/boards, and track is human or agent. Keep task and board consistent.

# Public standings for T1.
curl --fail-with-body -sS --get "$VE_API_BASE/challenge/leaderboard" \
  --data-urlencode "task=T1"

# One board, Agent Team track. Use a board key from /challenge/boards.
curl --fail-with-body -sS --get "$VE_API_BASE/challenge/leaderboard" \
  --data-urlencode "task=T1" \
  --data-urlencode "board=T1:val" \
  --data-urlencode "track=agent"

# Aggregate standings across tasks for Human Teams.
curl --fail-with-body -sS --get "$VE_API_BASE/challenge/overall" \
  --data-urlencode "track=human"

Read rows for competing teams, reference for baselines and partners for partner reference teams. Partner entries have no official rank or prize eligibility. The response also reports phase and shows_scores. A phase that does not publish scores can return empty rows with counts or a note. Test teams and excluded teams do not appear in public competition standings.

/challenge/overall aggregates the best scores across task boards; it supports optional task and track filters. Use individual board leaderboards for board standings. In the example above, replace T1:val with the current board key when the competition moves to the test split.

6. Agent Team evidence

Human Teams do not upload Agent evidence. Agent Teams declare the framework and model, then attach evidence to each prediction’s submission ID. Keys created here for Agent Teams include the necessary permissions automatically.

curl --fail-with-body -sS "$VE_API_BASE/challenge/submissions" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -H "Idempotency-Key: agent-prediction-001" \
  -F "task=T1" \
  -F "model=My agent method" \
  -F "agent_framework=custom" \
  -F "agent_model=YOUR_MODEL_IDENTIFIER" \
  -F "architecture=My agent architecture" \
  -F "[email protected]"

A valid Agent prediction starts as awaiting_evidence. Query its evidence endpoint first: required, kinds, min_kinds, required_kind, files, max_bytes and max_total_bytes describe the current requirements. missing lists recommended kinds not yet attached; it is not a requirement to upload every listed kind.

# Set VE_SUBMISSION_ID to the id returned by the agent upload.
curl --fail-with-body -sS "$VE_API_BASE/challenge/teams/evidence/$VE_SUBMISSION_ID" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

curl --fail-with-body -sS "$VE_API_BASE/challenge/teams/evidence/$VE_SUBMISSION_ID" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -F "kind=trajectory" \
  -F "note=Complete execution trace for this prediction" \
  -F "[email protected]"

curl --fail-with-body -sS "$VE_API_BASE/challenge/teams/evidence/$VE_SUBMISSION_ID" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY" \
  -F "kind=prompts" \
  -F "[email protected]"

Supported kinds are trajectory (execution trace), prompts, harness (orchestration code) and other. Send kind and file, with an optional note. The current gate requires at least two distinct kinds, including required_kind when it is non-empty; trajectory plus prompts is an example. Read the endpoint’s requirements rather than assuming they will never change.

Evidence uploads report kinds, needs_kinds, needs_kind, has_required_kind and queued. When the gate is satisfied, the retained prediction moves to queued. Evidence uploads are not deduplicated by Idempotency-Key: after a timeout, check the evidence list before resending. If the prediction was reclaimed, read the returned note and make a new prediction submission rather than continuing to poll the old one.

7. The same rules and quotas as the portal

• For ordinary teams, API and website uploads share one budget per team, task and UTC day. Partner teams instead use a personal budget of 2 uploads per subtask per UTC day, with a separate allowance for each T2 subtask. Multiple keys or platforms do not create more attempts.
• For ordinary teams, /challenge/integration/quota returns daily.T1/T2/T3: used and limit for scoring, uploads and upload_limit for stored attempts. Rejected files count toward the upload limit but do not spend a scoring attempt. Format checks spend neither.
• quota_credit reports any organiser-granted recovery credits. Credits do not bypass the upload ceiling or the final-phase board budget.
• In the final phase, official_per_board reports a phase-wide allowance per board. It does not reset each day. Format checks remain available.
• The key issuer must have accepted the current Rules and Terms. Missing or outdated acceptance blocks a new upload with 409. Sign in to your account to accept them; a key cannot do this for you.
• Phase availability, team eligibility, file validation, Agent declarations/evidence and score visibility all follow the portal’s rules.

curl --fail-with-body -sS "$VE_API_BASE/challenge/me" \
  -H "Authorization: Bearer $VE_CHALLENGE_API_KEY"

curl --fail-with-body -sS "$VE_API_BASE/challenge/documents"

Check stale_consents in /challenge/me. Ordinary teams may have ten active keys per team; partner-team members may each have ten personal keys. Keys expire after their chosen duration, no later than the submission deadline. Revocation or the issuer leaving invalidates the key. Captain changes also invalidate ordinary team keys; Partner personal keys stay with their issuing member.

8. Safe retries and error handling

Use a unique Idempotency-Key for each new official prediction. It accepts 1–128 letters, digits or ._:-. Keep the same header, file bytes, filename and form fields for every retry of that prediction.

An identical retry returns the original upload response and ID without creating a second job or spending another attempt, even after quota exhaustion. Rotating the API key does not reset this record. A different payload with the same request key returns 409. Use the detail endpoint for the current status; a replay returns the original upload response.

On timeouts or 5xx responses, back off between retries, for example 2, 4, then 8 seconds. Check the JSON detail field for HTTP errors. Do not automatically retry 4xx responses unchanged.