Studio events and forms

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:

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:

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:

{
  "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:

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

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.

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.

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:

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.

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
      }
    ]
  }'

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.

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}'

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:

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.

Start

Core Concepts

Product reference

Select a studio

Read events

Inspect reusable definitions

Create a draft revision

Update a draft

Publish a revision

Semantic fields

​Select a studio

​Read events

​Inspect reusable definitions

​Create a draft revision

​Update a draft

​Publish a revision

​Semantic fields

Select a studio

Read events

Inspect reusable definitions

Create a draft revision

Update a draft

Publish a revision

Semantic fields