> ## Documentation Index > Fetch the complete documentation index at: https://docs.runflow.io/llms.txt > Use this file to discover all available pages before exploring further. # Create and dispatch a batch > Create a ``Batch`` + N child ``Run`` rows + thin ``batch_items`` junction rows. Only binding-capable (template-backed) models support batches today — per-provider-only models return 422 on this route. **Idempotency**: customers may send an ``Idempotency-Key`` request header. Handling lives in the global ``IdempotencyMiddleware`` (``core/middleware/idempotency.py``) — not this route. Same key + same body replays the cached 201 (same ``batch_id``, no second batch); same key + different body returns ``409 CONFLICT``; absent header falls through to first-write-wins. ## OpenAPI ````yaml /api/openapi.public.json post /v1/models/{owner}/{slug}/batches openapi: 3.1.0 info: title: Runflow API version: 0.1.0 description: >- Public Runflow API. Run AI image and video models, manage media, inspect run history, and configure webhooks. Auth: HTTP Bearer. This document is the customer integration surface only. Admin and internal operations plus generic system reference-data tables are intentionally omitted. servers: - url: https://api.runflow.io description: Production security: - HTTPBearer: [] tags: - name: Models description: >- Browse the model catalog and dispatch model runs. The primary surface for running AI image and video generation. - name: Runs description: >- Inspect, cancel, and re-run model executions. Fetch logs, node-runs, and callback delivery history. - name: Media description: >- Upload images and videos as inputs. Organize assets into folders. Three-step presigned upload flow for large files. - name: Batches description: >- Run a model on multiple inputs in one request. Includes per-item status and a single callback when the batch completes. - name: Evaluations description: >- Submit an image generated anywhere for automated quality evaluation, then read a pass verdict, a 0-1 score, and structured issues. No Runflow run required. - name: Webhooks description: >- Subscribe to platform events. Inspect delivery history, redeliver failed callbacks, manage signing secrets. - name: Account description: Read your account identity and credit balance. - name: Status description: Health and readiness probes for the API. paths: /v1/models/{owner}/{slug}/batches: post: tags: - Models summary: Create and dispatch a batch description: >- Create a ``Batch`` + N child ``Run`` rows + thin ``batch_items`` junction rows. Only binding-capable (template-backed) models support batches today — per-provider-only models return 422 on this route. **Idempotency**: customers may send an ``Idempotency-Key`` request header. Handling lives in the global ``IdempotencyMiddleware`` (``core/middleware/idempotency.py``) — not this route. Same key + same body replays the cached 201 (same ``batch_id``, no second batch); same key + different body returns ``409 CONFLICT``; absent header falls through to first-write-wins. operationId: createModelBatch parameters: - name: owner in: path required: true schema: type: string title: Owner - name: slug in: path required: true schema: type: string title: Slug - name: X-Organization-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Organization-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchCreateResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Forbidden — inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, ORGANIZATION_MEMBERSHIP_REQUIRED, ROLE_UNRESOLVED, IMPERSONATION_READ_ONLY) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: BatchCreate: properties: input: items: additionalProperties: true type: object type: array maxItems: 100 minItems: 1 title: Input metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata callback_url: anyOf: - type: string maxLength: 2048 - type: 'null' title: Callback Url additionalProperties: false type: object required: - input title: BatchCreate description: |- POST body for creating a batch. ``input`` is an array of per-item objects. Each item is validated independently against the target model's ``ModelInput`` declarations. Each item may carry an optional ``client_ref`` (≤255 chars, stripped before model validation); the model's own input shape fills the rest. BatchCreateResponse: properties: id: type: string format: uuid title: Id target_type: type: string title: Target Type target_id: type: string format: uuid title: Target Id status_code: type: string title: Status Code items_total: type: integer title: Items Total items_succeeded: type: integer title: Items Succeeded items_failed: type: integer title: Items Failed items_cancelled: type: integer title: Items Cancelled items: items: $ref: '#/components/schemas/BatchItemHandle' type: array title: Items output: anyOf: - additionalProperties: true type: object - type: 'null' title: Output cost: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Cost metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata callback_url: anyOf: - type: string - type: 'null' title: Callback Url created_at: type: string format: date-time title: Created At started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At additionalProperties: false type: object required: - id - target_type - target_id - status_code - items_total - items_succeeded - items_failed - items_cancelled - items - created_at title: BatchCreateResponse description: |- POST /batches response — batch fields + ``items`` handle list. Shape matches the customer contract (docs/api/contracts/ batch-endpoint-api-surface.md "Response shape" section). Distinct from ``Batch.FullValidator`` which exposes additional internal fields for admin callers. ErrorResponse: properties: code: type: string title: Code message: type: string title: Message errors: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Errors type: object required: - code - message title: ErrorResponse description: Standard error envelope — matches exception handler output. BatchItemHandle: properties: id: type: string format: uuid title: Id sequence_index: type: integer title: Sequence Index client_ref: anyOf: - type: string - type: 'null' title: Client Ref run_id: type: string format: uuid title: Run Id status_code: type: string title: Status Code type: object required: - id - sequence_index - run_id - status_code title: BatchItemHandle description: |- Lean per-item correlation handle for POST /batches responses and ``GET /batches/{id}`` inline items. For the full per-item projection (input/output/cost/timestamps), use ``GET /batches/{id}/items``. securitySchemes: HTTPBearer: type: http scheme: bearer ````