Create match prediction

Developing

POST

https://uat-integration.returning.ai/apis/v1/match-predictions

Match Predictions

Create a draft match prediction owned by the API-key's community.

Auth: Bearer API key with matchPredictions permission.

Idempotency: Idempotency-Key header required. Replaying the same key with the same body returns the original 201 response. Same key with a different body returns 409 IDEMPOTENCY_KEY_CONFLICT.

Lifecycle: newly created matches start in draft. Use PATCH to edit and POST /publish to transition to scheduled.

Retention: draft matches have no auto-expiry. Terminal-state operations retain data 7 days (bulk-jobs TTL).

Rate limit: standard per-community limit — 429 RATE_LIMITED with Retry-After header on breach.

Freeze: while MATCH_PREDICTION_FROZEN=true, every endpoint returns 503 MATCH_PREDICTION_FROZEN.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢201Success — Created

application/json

Match prediction created successfully.

Bodyapplication/json

🟠400Validation failed

🟠401Unauthorized

🟠403Forbidden

🟠409Conflict

🟠429Rate limited

🔴503Service unavailable / Frozen

🔴500Internal error

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://uat-integration.returning.ai/apis/v1/match-predictions' \
--header 'Idempotency-Key: 01HXYZABCDEFG1234567890' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "title": "Australia vs New Zealand",
  "description": "<p>Predict the final score.</p>",
  "externalReference": "provider-fixture-123",
  "teamA": {
    "name": "Australia",
    "imageUrl": "https://cdn.example.com/teams/australia.png"
  },
  "teamB": {
    "name": "New Zealand",
    "imageUrl": "https://cdn.example.com/teams/new-zealand.png"
  },
  "predictionStartAt": "2026-08-06T08:00:00.000Z",
  "lockAt": "2026-08-07T09:59:00.000Z",
  "kickoffAt": "2026-08-07T10:00:00.000Z",
  "scoreBasis": "regulation",
  "rewards": {
    "correctResult": {
      "coins": 100,
      "xp": 50
    },
    "exactScoreBonus": {
      "coins": 200,
      "xp": 100
    }
  },
  "entryCost": {
    "enabled": false,
    "coins": 0
  },
  "viewPermission": {
    "roleIds": [],
    "userIds": []
  }
}'

Response Example

201 - Created

Fresh 201 on happy path.

{
  "meta": {
    "status": "success",
    "statusCode": 201,
    "code": "MATCH_PREDICTION_CREATED",
    "requestId": "req_01abc",
    "timestamp": "2026-08-07T12:00:00.000Z"
  },
  "message": "Match prediction created.",
  "data": {
    "id": "mp_01abc",
    "status": "draft",
    "version": 1
  }
}

Modified at 2026-09-25 08:29:20

Get Rolling Calculation Data

List match predictions