Bulk update match predictions

Submit a bulk-update job for 1-100 match predictions. Each item is patched via the same version-guarded PATCH pipeline; per-item errors don't roll back sibling successes.

Auth: Bearer API key with matchPredictions permission.

Body: JSON only. Content-Type: application/json required (415 UNSUPPORTED_MEDIA_TYPE otherwise). items length 1-100 inclusive; 0 → 400 EMPTY_ITEMS, 101+ → 400 TOO_MANY_ITEMS. Duplicate matchPredictionId in the same request → 400 DUPLICATE_ITEM_ID.

Idempotency: Idempotency-Key header required. Same key + same body returns original 202 with same jobId. Same key + different body → 409 IDEMPOTENCY_KEY_CONFLICT.

Async: 202 returns operationId (mpbu_...), statusUrl, resultsUrl. Poll status endpoint until terminal state (completed, completed_with_errors, or failed).

Cross-community items in the payload return MATCH_PREDICTION_NOT_FOUND per-item on the results endpoint — no existence leak.

Retention: job metadata retained 7 days via TTL.

Rate limit: 429 RATE_LIMITED with Retry-After header.

Freeze: 503 MATCH_PREDICTION_FROZEN while ops has frozen the API.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Responses

🟢202Accepted

application/json

Bulk-update job accepted. Poll statusUrl for job status; resultsUrl for per-item outcomes.

Bodyapplication/json

🟠400Validation failed

🟠401Unauthorized

🟠403Forbidden

🟠409Idempotency key conflict

🟠415Unsupported media type

🟠429Rate limited

🔴503Bulk-update queue unavailable / Frozen

🔴500Internal error

curl --location 'https://adss-uat-integration.returning.ai/apis/v1/match-predictions/bulk-updates' \ --header 'Idempotency-Key: 01HXYZABCDEFG1234567890' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "items": [ { "matchPredictionId": "mp_01abc", "version": 3, "changes": { "lockAt": "2026-08-08T09:59:00.000Z", "kickoffAt": "2026-08-08T10:00:00.000Z" } }, { "matchPredictionId": "mp_02abc", "version": 1, "changes": { "title": "Updated fixture title" } } ] }'

{ "meta": { "status": "success", "statusCode": 202, "code": "MATCH_PREDICTION_BULK_UPDATE_ACCEPTED", "requestId": "req_01abc", "timestamp": "2026-08-07T12:00:00.000Z" }, "message": "Bulk update job accepted.", "data": { "operationId": "mpbu_01abc", "type": "bulk_update", "status": "queued", "submitted": 2, "statusUrl": "/v1/match-predictions/bulk-jobs/mpbu_01abc", "resultsUrl": "/v1/match-predictions/bulk-jobs/mpbu_01abc/results" } }

Bulk update match predictions

Request

Responses