Skip to navigation

create batch

Create a batch processing job from a JSONL file. Requires the Scale plan or above and approval for your organization. Access is disabled by default, including for new Scale subscriptions. Contact support@sync.so to request access. Without approval, creation and dry runs return 403 batch_access_not_enabled. Approved organizations on other plans get 402 plan_feature_unavailable with requiredPlan. Send the file in multipart field input (or the accepted file alias); it must be 5 MB or smaller and contain 20-500 records by default. A batch is queued and holds one slot of your plan’s batch concurrency limit; more active batches than that returns 429 concurrency_limit_reached. Each line must contain request_id, endpoint exactly /v2/generate, and a generation payload. To send the records as a JSON array instead of a file, use “Create Batch from Rows”, the application/json form of the same endpoint. Errors name a refused record by its 1-based line, counting non-empty lines: dialogue edit refusals return it as lineNumber, other record errors only in message.

Authentication

x-api-keystring
API Key authentication via header

Request

This endpoint expects a multipart form containing a file.
inputfileRequired

JSONL file containing batch requests. Send it in multipart field input (or file alias). Each non-empty line must contain request_id, endpoint exactly /v2/generate, and payload as a CreateGenerationDto object. Minimum 20 records required, maximum 500 records by default, no duplicate request_id values, and maximum file size 5 MB.

webhook_urlstringOptional

Optional webhook URL to receive batch completion notifications. A POST request will be sent when the batch completes or fails, with a Sync-Signature header (t=<unix>,v1=<hmac_sha256>) signed with the organization webhook secret and a stable Sync-Delivery-Id header. Delivery is attempted up to six times over about two hours.

dry_runbooleanOptionalDefaults to false

When true, validates the JSONL file and returns { "status": "VALIDATED" } without creating a batch. Requires the same organization approval and plan as batch creation.

Response

This endpoint returns an object.
Batch Responseobject
OR
Validation Responseobject

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error