> ## Documentation Index
> Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Studio events and forms

> Read studio events and manage versioned event forms without exposing roster or guardian data.

The studio management API reads event metadata and manages event form schemas.
It does not expose athletes, guardians, roster rows, orders, or CRM records.

Every studio-owned request includes the studio's stable public ID:

```http theme={null}
GET /v1/studios/stu_example/events
```

The path selects the requested studio. Authorization still comes from the API
key. Batch Relay verifies that a studio-owned key belongs to that studio or
that an individual key has an active grant for it.

## Select a studio

List the studios available to the current credential:

```bash theme={null}
curl 'https://api.batchrelay.com/v1/studios?limit=50' \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY"
```

A single-studio integration receives one item. Multi-studio integrations
should retain the selected `stu_...` ID and use it in every studio request.
List responses use this envelope:

```json theme={null}
{
  "items": [{ "id": "stu_example", "name": "Example Studio" }],
  "next_cursor": null,
  "is_done": true
}
```

Pass `next_cursor` back as `cursor` to read the next page. The `limit` must be
between 1 and 100.

The CLI selects the only accessible studio automatically. If the credential
can access more than one studio, pass `--studio` or save a default on the
profile:

```bash theme={null}
batchrelay studios list --pretty
batchrelay --profile agency profiles set-studio stu_example
batchrelay --profile agency events list --pretty
batchrelay --profile agency --studio stu_other events list --pretty
```

The saved studio ID is a local preference, not authorization. The API still
checks the selected studio against the credential on every request.

## Read events

```bash theme={null}
curl https://api.batchrelay.com/v1/studios/stu_example/events \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY"
```

An event response contains operational metadata and its active form revision
ID. It never includes submitted form answers or participant records.

## Inspect reusable definitions

Reusable definitions are read-only in V1. They can seed a new event revision,
but changing a definition does not alter revisions already attached to events.

```bash theme={null}
curl https://api.batchrelay.com/v1/studios/stu_example/form-definitions \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY"
```

## Create a draft revision

Create a draft from a reusable definition, explicit fields, or both. Supply an
idempotency key so retrying an interrupted request cannot create a second
draft.

```bash theme={null}
curl -X POST \
  https://api.batchrelay.com/v1/studios/stu_example/events/evt_example/form-revisions \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-draft-20260829-001" \
  -d '{
    "form_definition_id": "frm_example",
    "fields": [
      {
        "key": "jersey_number",
        "label": "Jersey number",
        "input_type": "number",
        "required": false,
        "semantic_key": "athlete.jersey_number",
        "sort_order": 2
      }
    ]
  }'
```

Batch Relay resolves semantic keys against the platform vocabulary and rejects
an incompatible input type.

The matching CLI command reads the request body from a file or stdin:

```bash theme={null}
batchrelay forms revisions create \
  --event evt_example \
  --input form-revision.json \
  --idempotency-key form-draft-20260829-001 \
  --pretty
```

## Update a draft

Only drafts can be changed. Pass the `edit_version` returned by the prior read
or write. A stale version returns `409 form_revision_conflict` instead of
overwriting another edit.

```bash theme={null}
curl -X PATCH \
  https://api.batchrelay.com/v1/studios/stu_example/events/evt_example/form-revisions/frv_example \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_edit_version": 2,
    "fields": [
      {
        "key": "jersey_number",
        "label": "Jersey number",
        "input_type": "number",
        "required": true,
        "semantic_key": "athlete.jersey_number",
        "sort_order": 2
      }
    ]
  }'
```

```bash theme={null}
batchrelay forms revisions update frv_example \
  --event evt_example \
  --input form-revision-update.json \
  --expected-edit-version 2 \
  --pretty
```

## Publish a revision

Publishing makes the draft immutable, supersedes the prior active revision,
and updates the event's active revision pointer in one transaction. Publication
fails if the draft was based on an active revision that has since changed.

```bash theme={null}
curl -X POST \
  https://api.batchrelay.com/v1/studios/stu_example/events/evt_example/form-revisions/frv_example/publish \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-publish-20260829-001" \
  -d '{"expected_edit_version": 3}'
```

```bash theme={null}
batchrelay forms revisions publish frv_example \
  --event evt_example \
  --expected-edit-version 3 \
  --idempotency-key form-publish-20260829-001 \
  --pretty
```

Test keys cannot create, update, or publish revisions because forms are live
studio configuration. Anonymous sessions cannot access these routes.

## Semantic fields

Semantic fields use platform-owned keys such as `athlete.jersey_number`. Query
the vocabulary before generating a form:

```bash theme={null}
curl https://api.batchrelay.com/v1/semantic-fields \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY"
```

The response includes each field's compatible input types, status, and aliases.
Clients should persist the stable semantic key, not a label or internal ID.

All management list endpoints use the same cursor envelope. Treat cursors as
opaque values and stop when `is_done` is true.