Studio management

The studio management API reads event metadata, manages event form schemas, and manages a studio’s public storefront assortment. 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.

Storefront management

Each studio has one public storefront and one published assortment. Read it with:

curl https://api.batchrelay.com/v1/studios/stu_example/storefront \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY"

The response contains its current revision and the complete sellables array. A sellable is a catalog_item or package with its public ID. Replace the complete assortment with PATCH. This is an atomic, immediately published change, not a draft. Supply the revision you read, the entire next array, and an Idempotency-Key:

curl -X PATCH \
  https://api.batchrelay.com/v1/studios/stu_example/storefront \
  -H "Authorization: Bearer $BATCHRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: storefront-20260829-001" \
  -d '{
    "expected_published_revision": 4,
    "sellables": [
      { "type": "catalog_item", "id": "scp_example" },
      { "type": "package", "id": "spk_example" }
    ]
  }'

This requires storefronts:write and a Live API key. A stale expected_published_revision returns a conflict instead of overwriting a more recent published assortment. There is no separate storefront draft or publish endpoint yet.

Product and package edits

Studio product and package updates use their direct resource paths. Do not add /draft to either path:

PATCH /v1/studios/{studio_id}/products/{product_id}
PATCH /v1/studios/{studio_id}/packages/{package_id}

Both updates require the current expected_edit_version. When a published resource is changed, the server creates or updates its server-owned draft revision. Use the generated API reference for the complete request schemas.

Semantic fields

Semantic fields use platform-owned keys such as athlete.jersey_number. Query the vocabulary before generating a form. This catalog read is unauthenticated and is not scoped to a studio:

curl https://api.batchrelay.com/v1/catalog/semantic-fields

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

Storefront management

Product and package edits

Semantic fields

​Select a studio

​Read events

​Inspect reusable definitions

​Create a draft revision

​Update a draft

​Publish a revision

​Storefront management

​Product and package edits

​Semantic fields

Select a studio

Read events

Inspect reusable definitions

Create a draft revision

Update a draft

Publish a revision

Storefront management

Product and package edits

Semantic fields