> ## 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. # Create studio form definition > Requires forms:write. Creates reusable source from full form_spec. Stable option/field IDs, conditions, extensions and semantics round-trip. ## OpenAPI ````yaml https://api.batchrelay.com/openapi.json post /v1/studios/{studio_id}/form-definitions openapi: 3.1.0 info: description: >- Provider-neutral print catalog and prepared-media validation. This document covers only routes owned by the Go service; it deliberately excludes migration-proxied order lifecycle routes and all provider payloads. license: name: Proprietary url: https://github.com/SENTINELITE/Batch-Relay-Go/blob/main/README.md title: Batch Relay API version: 1.0.1 servers: - url: https://api.batchrelay.com security: [] tags: - description: >- Explicitly authorized purchaser context for studio order events. Event payloads remain free of contact details. name: Event context - description: Service health and the public API description. name: System - description: Test Mode session creation and API credential entry points. name: Authentication - description: >- Provider-neutral canonical catalog resources and platform-owned semantic definitions. name: Catalog - description: Studio-scoped guest checkout-link management. name: Checkout links - description: >- One-way operational event messages. Alert emails contain no message body and recipients read messages after Batch Relay authentication. name: Studio messages - description: >- Explicit, reviewable sandbox-to-Live promotion plans for forms, catalog, and storefront configuration. name: Sandbox promotions - description: Provider-neutral validation, quoting, and order lifecycle operations. name: Print orders - description: Managed fulfillment asset ingestion and metadata. name: Managed assets - description: Studio-scoped original asset upload sessions and objects. name: Studio assets - description: Prepared and confirmed event roster team changes. name: Event team changes - description: Authenticated studio, event, and form-management operations. name: Studio management - description: >- Authenticated studio retail catalog management. Draft and publication lifecycles are explicit per product or package. name: Studio catalog - description: >- Authenticated singular storefront assortment management. PATCH atomically publishes a new immutable assortment revision; no storefront draft lifecycle exists yet. name: Storefront - description: Managed media used by the studio retail catalog. name: Studio catalog assets - description: Template rendering job creation and retrieval. name: Template renders - description: >- Published browser-side template packages and short-lived server proof renders. Preview artifacts are never fulfillment artwork. name: Browser previews - description: API account and credential administration. name: API accounts - description: >- Standalone guest purchases; feature disabled by default. Temporary merchandise USD0.75 5x7 and USD1.50 8x10, plus authoritative shipping and tax. name: Consumer printing paths: /v1/studios/{studio_id}/form-definitions: parameters: - $ref: '#/components/parameters/ClientSurface' - $ref: '#/components/parameters/ClientVersion' - $ref: '#/components/parameters/InvocationMode' post: tags: - Studio Operations summary: Create studio form definition description: >- Requires forms:write. Creates reusable source from full form_spec. Stable option/field IDs, conditions, extensions and semantics round-trip. operationId: createStudioFormDefinition parameters: - $ref: '#/components/parameters/StudioDelegatedAuthorization' - description: Opaque public studio_id. Private Convex IDs are rejected. in: path name: studio_id required: true schema: type: string - $ref: '#/components/parameters/IdempotencyKey' requestBody: content: application/json: schema: $ref: '#/components/schemas/StudioFormDefinitionRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/FormDefinition' description: Authoritative Studio result '401': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: Invalid credential or expired/revoked delegated token '403': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: Wrong Studio, role, action scope or disabled Live effects '404': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: Resource unavailable in this Studio and lane '409': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: >- Stale resource, expired preview, dependency blocker or idempotency conflict '422': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: Invalid typed request or unsupported query '503': content: application/json: schema: $ref: '#/components/schemas/StudioOperationsError' description: Required adapter or delegated verification is not configured security: - bearerAuth: [] components: parameters: ClientSurface: description: >- Untrusted optional analytics hint naming the calling client surface. It never affects authorization, routing, pricing, or behavior. in: header name: X-BatchRelay-Client-Surface required: false schema: maxLength: 100 minLength: 1 type: string ClientVersion: description: >- Untrusted optional analytics hint naming the calling client version. It never affects authorization, routing, pricing, or behavior. in: header name: X-BatchRelay-Client-Version required: false schema: maxLength: 100 minLength: 1 type: string InvocationMode: description: >- Untrusted optional analytics hint naming the invocation mode. It never affects authorization, routing, pricing, or behavior. in: header name: X-BatchRelay-Invocation-Mode required: false schema: maxLength: 100 minLength: 1 type: string StudioDelegatedAuthorization: description: >- Original delegated Clerk OAuth bearer. Go independently verifies signature/current revocation, exact resource audience, allowed OAuth client and action scope. Caller must match attributed API key creator. Never send an unverified subject header. in: header name: X-BatchRelay-Delegated-Authorization required: false schema: type: string IdempotencyKey: in: header name: Idempotency-Key required: true schema: maxLength: 200 minLength: 1 type: string schemas: StudioFormDefinitionRequest: additionalProperties: false properties: description: anyOf: - type: string - type: 'null' form_spec: $ref: '#/components/schemas/FormSpecV2' required: - form_spec type: object FormDefinition: additionalProperties: false properties: created_at: type: string description: type: string edit_version: format: int64 type: integer environment: type: string fields: items: $ref: '#/components/schemas/FormField' maxItems: 200 type: array form_presentation: $ref: '#/components/schemas/FormPresentation' form_spec: $ref: '#/components/schemas/FormSpecV2' description: >- Versioned form definition with persistent option IDs. On writes, mutually exclusive with fields and form_presentation. Legacy revisions may omit this until their choices have IDs. id: description: Stable public form-definition ID. minLength: 1 type: string name: minLength: 1 type: string status: type: string studio_id: minLength: 1 type: string updated_at: type: string required: - id - studio_id - name - fields type: object StudioOperationsError: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object FormSpecV2: additionalProperties: false properties: fields: items: $ref: '#/components/schemas/FormSpecFieldV2' maxItems: 200 minItems: 1 type: array form_presentation: $ref: '#/components/schemas/FormPresentation' name: maxLength: 240 minLength: 1 type: string spec_version: const: 2 description: >- JSON specification version; independent of a form revision or draft edit version. type: integer required: - spec_version - name - fields type: object FormField: additionalProperties: false properties: allow_multiple: type: boolean boolean_display: enum: - toggle - yes_no type: string description: maxLength: 2000 type: string input_type: enum: - text - number - select - checkbox - textarea - date - event_team type: string key: minLength: 1 type: string label: minLength: 1 type: string option_ids: items: maxLength: 160 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,160}$ type: string maxItems: 200 type: array uniqueItems: true options: items: minLength: 1 type: string maxItems: 200 type: array options_display: enum: - dropdown - pills type: string placeholder: type: string required: type: boolean semantic_key: minLength: 1 type: string semantic_label: minLength: 1 type: string show_when: $ref: '#/components/schemas/FormCondition' sort_order: minimum: 0 type: integer required: - key - label - input_type - required - sort_order type: object FormPresentation: additionalProperties: false description: >- Typed public form layout. It intentionally excludes heroStorageId, Convex IDs, athlete data, guardian data, and submitted answers. properties: description: type: string pages: items: $ref: '#/components/schemas/FormPresentationPage' maxItems: 50 minItems: 1 type: array public_title: minLength: 1 type: string required: - public_title - pages type: object FormSpecFieldV2: additionalProperties: false properties: allow_multiple: type: boolean boolean_display: enum: - toggle - yes_no type: string description: maxLength: 2000 type: string input_type: enum: - text - number - select - checkbox - textarea - date - event_team type: string key: maxLength: 160 minLength: 1 pattern: ^[a-z0-9]+(?:_[a-z0-9]+)*$ type: string label: minLength: 1 type: string options: items: additionalProperties: false properties: id: maxLength: 160 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,160}$ type: string label: maxLength: 160 minLength: 1 type: string required: - id - label type: object maxItems: 200 minItems: 1 type: array options_display: enum: - dropdown - pills type: string placeholder: type: string required: type: boolean semantic_key: minLength: 1 type: string show_when: $ref: '#/components/schemas/FormCondition' sort_order: minimum: 0 type: integer required: - key - label - input_type - required - sort_order type: object FormCondition: oneOf: - additionalProperties: false properties: field_key: maxLength: 160 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,160}$ type: string operator: const: is_one_of option_ids: items: maxLength: 160 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,160}$ type: string maxItems: 200 minItems: 1 type: array uniqueItems: true required: - field_key - operator - option_ids type: object - additionalProperties: false properties: field_key: maxLength: 160 minLength: 1 pattern: ^[A-Za-z0-9_-]{1,160}$ type: string operator: const: equals value: type: boolean required: - field_key - operator - value type: object - type: 'null' FormPresentationPage: additionalProperties: false properties: description: type: string id: description: Public stable layout page identifier, not a Convex document ID. minLength: 1 type: string rows: items: $ref: '#/components/schemas/FormPresentationRow' maxItems: 100 minItems: 1 type: array title: minLength: 1 type: string required: - id - title - rows type: object FormPresentationRow: additionalProperties: false properties: fields: items: $ref: '#/components/schemas/FormPresentationFieldPlacement' maxItems: 2 minItems: 1 type: array id: description: Public stable layout row identifier, not a Convex document ID. minLength: 1 type: string required: - id - fields type: object FormPresentationFieldPlacement: additionalProperties: false properties: field_key: minLength: 1 type: string width: enum: - full - half type: string required: - field_key - width type: object securitySchemes: bearerAuth: bearerFormat: Batch Relay API key or anonymous session description: >- Batch Relay scoped API key or an anonymous Test Mode session. Scope names document required capabilities. Anonymous sessions are sandbox-only and do not authorize studio, event, billing, or Live Mode operations. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.