Batches

Submit an async batch job

Submit an async batch job for processing.

Requires the Idempotency-Key header — a client-supplied string that scopes deduplication per account. Retrying with the same key returns the same job id (no duplicate row), backed by the UNIQUE(account_id, idempotency_key) constraint on the batch_jobs table (migration 122).

Returns 202 Accepted with {id, status:"queued"}. The job id can be used with GET /v1/batches/{id} to poll for status and results.

Batch submission is accepted but not processed until the worker ships (BATCH2-01, discovery-gated). Submitted batches persist as 'queued' rows in batch_jobs until the processing worker is activated. This is intentional — the scaffold lets developers integrate the contract end-to-end while the async execution infrastructure is under active development.

Idempotency: A retried POST with the same Idempotency-Key (for the same account) returns the existing job id with 202 — no duplicate row is created. Two different accounts may reuse the same key string without conflict (uniqueness is scoped per account).

Rate limit: 10/minute per account (provisional).

Returns 400 if the Idempotency-Key header is empty or whitespace. Returns 401 if not authenticated. Returns 413 if any single operation exceeds 8 KB or the whole payload exceeds 1 MB. Returns 422 if the Idempotency-Key header is absent.

post/v1/batches

Request

  • Base URL: https://api.scholarfeed.org (the document declares no server; this is the origin it was published from)
  • URL: https://api.scholarfeed.org/v1/batches
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Request body

requestsobject[] required

List of operations to run in batch. Shape is provisional and finalised when the worker ships (BATCH2-01). Maximum 10,000 operations per batch — larger batches should be split across multiple jobs.

Response

Successful Response

idstring required

UUID of the created batch job. Use this with GET /v1/batches/{id} to poll status.

statusstring required

Initial job status. Always 'queued' — the batch has been accepted and persisted, but the processing worker (BATCH2-01) is not yet active. The status will remain 'queued' until the worker ships.

Changes

No recorded changes to this operation across all 1 revision of this API.