> ## Documentation Index > Fetch the complete documentation index at: https://docs.matil.ai/llms.txt > Use this file to discover all available pages before exploring further. # Process (batch) > Submit multiple items for processing in a single request. Each item contains its own documents and optional metadata. Returns immediately with a `batch_id` and the total item count. Results are delivered via webhook as items complete. ## Request body - `requests` (required): Array of batch items (max 100). Each item has `documents` (required) and `metadata` (optional). - `webhook` (required): Object with `url`, `secret` (optional), and `incremental` (optional, defaults to `true`). When `incremental` is `true`, a webhook is sent as each item completes. When `false`, a single webhook is sent when the entire batch finishes. ## Webhook events - `batch.item.completed`: A single item finished processing (incremental mode). - `batch.completed`: The entire batch finished. - `batch.failed`: All items in the batch failed. ## OpenAPI ````yaml /api-reference/openapi.json post /v3/deployments/{deployment_id}/batch openapi: 3.1.0 info: title: matil API description: Structured data extraction for documents version: 3.0.0 servers: - url: https://api.matil.ai security: - ApiKeyAuth: [] paths: /v3/deployments/{deployment_id}/batch: post: tags: - Deployments summary: Process (batch) description: >- Submit multiple items for processing in a single request. Each item contains its own documents and optional metadata. Returns immediately with a `batch_id` and the total item count. Results are delivered via webhook as items complete. ## Request body - `requests` (required): Array of batch items (max 100). Each item has `documents` (required) and `metadata` (optional). - `webhook` (required): Object with `url`, `secret` (optional), and `incremental` (optional, defaults to `true`). When `incremental` is `true`, a webhook is sent as each item completes. When `false`, a single webhook is sent when the entire batch finishes. ## Webhook events - `batch.item.completed`: A single item finished processing (incremental mode). - `batch.completed`: The entire batch finished. - `batch.failed`: All items in the batch failed. operationId: process_batch_v3_deployments__deployment_id__batch_post parameters: - name: deployment_id in: path required: true schema: type: string format: uuid title: Deployment Id - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization - name: x-api-key in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key - name: X-Tenant-ID in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Tenant-Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchProcessRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchProcessResponse' '400': description: >- Document error. Possible codes: DOCUMENT_DOWNLOAD_ERROR, DOCUMENT_URL_NOT_FOUND, DOCUMENT_URL_ACCESS_DENIED, DOCUMENT_URL_RETURNED_HTML, DOCUMENT_TOO_LARGE, DOCUMENT_URL_UNREACHABLE. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: DOCUMENT_DOWNLOAD_ERROR message: Failed to download document from the provided URL details: null '401': description: >- Authentication required. Provide a valid `x-api-key` or `Authorization: Bearer` token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: AUTHENTICATION_REQUIRED message: Authentication required. Provide a valid x-api-key header. details: null '402': description: Insufficient credits. Top up your balance to continue processing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: INSUFFICIENT_CREDITS message: >- Insufficient credits. Top up your balance to continue processing. details: null '404': description: No valid deployments found for the provided identifiers. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: DEPLOYMENT_NOT_FOUND message: No valid deployment found for the provided ID. details: null '422': description: Validation error. Check request body and document format. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: VALIDATION_ERROR message: Batch requests must contain between 1 and 100 items. details: null components: schemas: BatchProcessRequest: properties: requests: items: $ref: '#/components/schemas/BatchItem' type: array maxItems: 100 minItems: 1 title: Requests description: >- List of items to process. Each item contains documents and optional metadata. webhook: $ref: '#/components/schemas/WebhookConfig' description: Webhook configuration for receiving processing results type: object required: - requests - webhook title: BatchProcessRequest description: Request for batch document processing via deployment. BatchProcessResponse: properties: batch_id: type: string format: uuid title: Batch Id description: Unique identifier for the batch status: type: string title: Status description: Initial batch status default: pending total_items: type: integer title: Total Items description: Number of items in the batch resource_type: type: string title: Resource Type description: Type of resource being processed default: structure resource_id: type: string format: uuid title: Resource Id description: ID of the structure being processed resource_version_number: type: integer title: Resource Version Number description: Version number of the structure created_at: type: string format: date-time title: Created At description: When the batch was created type: object required: - batch_id - total_items - resource_id - resource_version_number - created_at title: BatchProcessResponse description: Response for batch processing request creation. ErrorResponse: type: object properties: error: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object nullable: true description: Additional context when available. required: - error - message BatchItem: properties: metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: >- Client-provided metadata for correlation. Returned unchanged in responses. documents: items: anyOf: - $ref: '#/components/schemas/DocumentInputText' - $ref: '#/components/schemas/DocumentInputURL' - $ref: '#/components/schemas/DocumentInputBase64' - $ref: '#/components/schemas/DocumentInputId' type: array minItems: 1 title: Documents description: List of documents to process for this item type: object required: - documents title: BatchItem description: Single item in a batch request. WebhookConfig: properties: url: type: string title: Url description: URL to receive webhook events secret: anyOf: - type: string - type: 'null' title: Secret description: >- Your secret for HMAC-SHA256 signature verification. If provided, each webhook includes X-Matil-Signature header. incremental: type: boolean title: Incremental description: >- If true, sends a webhook for each item as it completes (batch.item.completed). If false, only sends the final batch.completed webhook when all items are processed. default: true type: object required: - url title: WebhookConfig description: >- Configuration for webhook delivery. Webhooks are sent as POST requests with JSON payload. If a secret is provided, each request includes an X-Matil-Signature header for verification. Retry behavior (automatic): - 3 retry attempts with exponential backoff - 30 second timeout per request - Client must return 2xx status within timeout DocumentInputText: properties: type: type: string const: text title: Type description: Document type indicator for direct text content default: text text: type: string title: Text description: Raw text content to process examples: - |- Invoice #12345 Date: 2024-01-15 Total: $1,234.56 metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Optional metadata for processing hints type: object required: - text title: DocumentInputText description: Direct text content for processing. DocumentInputURL: properties: type: enum: - url description: >- Document type indicator for URL reference. Only 'url' is shown in the schema. type: object required: - url title: DocumentInputURL description: >- URL reference to fetch document from. Accepts type "url" (shown in schema), but also allows "pdf", "png", etc. at runtime. DocumentInputBase64: properties: type: type: string const: base64 title: Type description: Document type indicator for base64-encoded content default: base64 content: type: string maxLength: 70000000 minLength: 1 title: Content description: Base64-encoded document bytes examples: - JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9MZW5ndGg... mime_type: anyOf: - type: string maxLength: 100 - type: 'null' title: Mime Type description: >- MIME type of the encoded document (e.g., 'application/pdf'). If not provided, will be auto-detected examples: - application/pdf - image/jpeg - image/png - text/plain - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet filename: anyOf: - type: string maxLength: 255 minLength: 1 - type: 'null' title: Filename description: Original filename for storage and processing hints examples: - invoice.pdf - receipt.jpg - document.txt metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Optional metadata for processing hints type: object required: - content title: DocumentInputBase64 description: |- Base64-encoded document for inline processing. Allows direct submission of document bytes as base64-encoded strings, eliminating the need for URL fetching or pre-upload steps. DocumentInputId: properties: type: type: string const: id title: Type description: >- Document type indicator - references a document previously uploaded via POST /documents default: id id: type: string format: uuid title: Id description: >- ID of document previously uploaded and processed via POST /documents endpoint examples: - 550e8400-e29b-41d4-a716-446655440000 metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata description: Optional metadata for processing hints type: object required: - id title: DocumentInputId description: Reference to pre-uploaded MATIL document. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````