# Generate Playground sample cases

```http
POST /api/public/v1/competitions/modular-arithmetic-challenge/playground/sample
Content-Type: application/json
```

**Scope**: `playground.write`.

Generates an ordered set of deterministic practice cases for one tier. This is a stateless practice operation: it does not create a Playground Run or formal submission, persist a case collection, or consume Playground credits. It requires neither competition enrollment nor a Competition Team and is independent of the formal-submission window. Normal API [rate limits](../../../rate-limiting.md) still apply.

The endpoint is available for a publicly visible active or closed competition only while `capabilities.playground` is `true`. A draft or disabled Playground returns `404 NOT_FOUND`.

## Deterministic replay

- Omit `seed` to let the service create a new 32-character lowercase hexadecimal replay seed.
- To replay a sample, send the returned `seed` unchanged with the same `tierId`. For Public API v1, the same `seed`, `tierId`, and `count` return the same cases in the same order with the same `caseId` values.
- Increasing `count` with the same `seed` and `tierId` preserves the existing prefix. For example, the first two cases from `count: 5` are the same as the two cases from `count: 2`.
- A `caseId` is an opaque, versioned practice-case identifier. It has no per-case expiry and does not depend on a stored Run. Pass it unchanged to [Check a Playground answer](./check-playground-answer.md); do not parse or construct it.

Practice seeds and cases are separate from the competition's frozen official evaluation batches. They do not reveal official cases, answers, or scoring seeds.

## Request fields

| Field    | Type    | Required | Default | Description |
| :------- | :------ | :------: | :------ | :---------- |
| `tierId` | integer | No       | `1`     | Tier ID from [List Playground tiers](./list-playground-tiers.md), currently `0` through `10`. |
| `count`  | integer | No       | `5`     | Number of cases to generate, from `1` through `50` inclusive. |
| `seed`   | string  | No       | —       | Exactly 32 lowercase hexadecimal characters. Reuse a seed returned by this endpoint, or omit the field to generate one. |

## Example request

```bash
curl -X POST \
  "https://api.sair.foundation/api/public/v1/competitions/modular-arithmetic-challenge/playground/sample" \
  -H "Authorization: Bearer $SAIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tierId": 1,
    "count": 2,
    "seed": "8eaf7b045445ab5fd23e6b0f8d3f0f86"
  }'
```

## Response fields

| Field                   | Type             | Always present | Description |
| :---------------------- | :--------------- | :------------: | :---------- |
| `seed`                  | string           | Yes            | The 32-character lowercase hexadecimal replay seed used for this sample. |
| `tierId`                | integer          | Yes            | Requested tier ID. |
| `cases`                 | `PracticeCase[]` | Yes            | Exactly `count` cases, ordered by their deterministic zero-based generation index. |
| `cases[].caseId`        | string           | Yes            | Opaque identifier to pass unchanged to the answer-check endpoint. |
| `cases[].tierId`        | integer          | Yes            | Same value as the response-level `tierId`. |
| `cases[].a`             | string           | Yes            | First operand as a canonical non-negative base-10 integer string. |
| `cases[].b`             | string           | Yes            | Second operand as a canonical non-negative base-10 integer string. |
| `cases[].p`             | string           | Yes            | Positive prime modulus for T1–T10; exactly `""` for T0. |
| `cases[].operation`     | string           | Yes            | `multiply` for T0; `modular_multiply` for T1–T10. |
| `cases[].operandDigits` | integer          | Yes            | Actual decimal length of the longer of `a` and `b`. |
| `cases[].modulusDigits` | integer          | Yes            | Actual decimal length of `p`; exactly `0` for T0. |

The operands and modulus are strings because the largest tiers exceed the safe integer range of common JSON clients. The response deliberately omits the expected answer. For T0, solve `a × b`; for T1–T10, solve `(a × b) mod p`, then submit the decimal result to the answer-check endpoint.

## Example response

```json
{
  "ok": true,
  "data": {
    "seed": "8eaf7b045445ab5fd23e6b0f8d3f0f86",
    "tierId": 1,
    "cases": [
      {
        "caseId": "mc1:8eaf7b045445ab5fd23e6b0f8d3f0f86:1:0",
        "tierId": 1,
        "a": "0",
        "b": "973142802",
        "p": "7",
        "operation": "modular_multiply",
        "operandDigits": 9,
        "modulusDigits": 1
      },
      {
        "caseId": "mc1:8eaf7b045445ab5fd23e6b0f8d3f0f86:1:1",
        "tierId": 1,
        "a": "1402897251",
        "b": "0",
        "p": "3",
        "operation": "modular_multiply",
        "operandDigits": 10,
        "modulusDigits": 1
      }
    ]
  }
}
```

Treat `caseId` as opaque even though the example shows its current serialized form.

## Errors

| Status | Code | When |
| :----: | :--- | :--- |
| `400` | `MALFORMED_BODY` | The JSON body, content type, top-level request shape, or field type is invalid. |
| `404` | `NOT_FOUND` | The competition does not exist, is a draft, or does not currently expose the Modular Arithmetic Playground. |
| `422` | `INVALID_TIER` | `tierId` is not present in the current Playground tier catalog. |
| `422` | `INVALID_COUNT` | `count` is outside `1` through `50`. |
| `422` | `INVALID_SEED` | A supplied `seed` is not exactly 32 lowercase hexadecimal characters. |

See [Errors](../../../errors.md) for authentication, scope, rate-limit, and standard error-envelope behavior.