# Quick start

From an API key to a first submission, using only `curl`.

## Before you start: create an API key

To call the public API you need an API key. Create one from your SAIR account settings:

1. Sign in to SAIR and open **Account settings → API keys**.
2. Create a key and select the scopes your use case needs (this walk-through uses `competition.read` and `competition.write`).
3. Copy the key — it is shown only once.

See [Authentication](../authentication.md) for the key format and scope reference.

## 1. Set environment variables

Use an API key with `competition.read` and `competition.write` scopes for this walk-through.

```bash
export SAIR_API_KEY="<your-api-key>"   # e.g. sair_a1b2c3d4_zR9...
export SAIR_COMPETITION_ID="modular-arithmetic-challenge"
```

## 2. Confirm the key

```bash
curl https://api.sair.foundation/api/public/v1/me \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

Response includes the key ID, its scopes, and the owner:

```json
{
  "ok": true,
  "data": {
    "key": { "id": "key_a1b2c3d4", "scopes": ["competition.read", "competition.write"], "expiresAt": "2026-08-01T00:00:00Z" },
    "owner": { "sairId": "U-9f7e1c00", "email": "you@example.com" }
  }
}
```

## 3. Read the submission spec

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/$SAIR_COMPETITION_ID" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

`data.submissionSpec` tells you what `payload` should look like. For `modular-arithmetic-challenge` it's `kind: model-reference` with required `modelName` and `commitHash`. For `igp24`, it is `kind: igp24-polynomial` with required `polynomials`.

Example response excerpt:

```json
{
  "ok": true,
  "data": {
    "submissionSpec": {
      "kind": "model-reference",
      "schema": { "...": "JSON Schema for payload" },
      "limits": { "maxBytes": null, "maxEntries": 3 }
    }
  }
}
```

## 4. Check eligibility

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/$SAIR_COMPETITION_ID/me" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

`data.canSubmit` should be `true`. Otherwise `data.submitBlockedReason` tells you what to fix.

## 5. Submit

The `payload` below is for `modular-arithmetic-challenge` (`kind: model-reference`). Other competitions use a different `payload` — build it from the `data.submissionSpec` you read in step 3. The IGP24 shape is shown right after.

```bash
curl -X POST "https://api.sair.foundation/api/public/v1/competitions/$SAIR_COMPETITION_ID/submissions" \
  -H "Authorization: Bearer $SAIR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "slot": 1,
    "payload": {
      "modelName": "your-team/your-model",
      "commitHash": "0123456789abcdef0123456789abcdef01234567"
    }
  }'
```

You'll get a `submissionId`. For `model-reference`, `slot` defaults to `1` and must not exceed `submissionSpec.limits.maxEntries`.

To read all current entries later, call the unified collection endpoint:

```bash
curl "https://api.sair.foundation/api/public/v1/competitions/$SAIR_COMPETITION_ID/submissions/mine" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

It always returns `{ "items": [...], "nextCursor": null }` inside `data`, including for competitions that allow only one current entry. The older `/submissions/me` endpoint remains available with its existing kind-specific response. To retrieve the stored text body (for `kind`s that have one), call `GET /api/public/v1/competitions/{competitionId}/submissions/{submissionId}/download`.

### Inverse Galois Problem (IGP24) submit shape

For `kind: igp24-polynomial`, submit one official polynomial-line string per item in `payload.polynomials`. A line may include a trailing comment; the exact `poly_disc_primes=[...]` comment supplies an optional `quicknfdisc` ramp hint:

```bash
curl -X POST "https://api.sair.foundation/api/public/v1/competitions/igp24/submissions" \
  -H "Authorization: Bearer $SAIR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "payload": {
      "polynomials": [
        "3,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1 # poly_disc_primes=[2,3]",
        "1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1"
      ]
    }
  }'
```

After submitting, call `GET /api/public/v1/competitions/igp24/submissions/mine` to read stored successful `verifiedPolynomials` from your submission history.

## Next

- For competitions that support Playground runs, iterate on your entry with [`POST /api/public/v1/competitions/{competitionId}/playground/runs`](../endpoints/playground.md#submit-a-run) before re-submitting.
- Check `submissionSpec.kind` and `submissionSpec.limits` before building competition-specific payloads.
- Browse community work in the [Contributor Network](../endpoints/contributor-network.md), including cheatsheets, solver templates, and model references. For `cheatsheet` and `solver-participation` submissions, you can record lineage via `meta.contributorNetworkItemId`; `model-reference` submissions do not accept that metadata field.
- Wire it into Python or TypeScript: see `examples/python/` and `examples/typescript/`.