Publish match prediction
Publish a draft match prediction so the traders it targets can see it and, from predictionStartAt, submit predictions.
- Method
- POST
- Path
https://api.returning.ai / v1/ match-predictions/ {matchPredictionId}/ publish - Permission
- matchPredictions
- Retries
- Safe to repeat; a published match returns 200
When to use this
- A draft is ready and should go live for the traders in its audience.
- You create matches ahead of time and publish each one when your campaign starts.
Authentication#
- Header
Authorization: Bearer <API_KEY>- Permission
- matchPredictionsShown in the dashboard as “Match Prediction”
Use a Community API key with matchPredictions, shown in the dashboard as Match Prediction, and keep it on your server. The key decides the community: you only see and change match predictions in that community, and an ID from another community returns 404, the same as an unknown ID. Personal API keys are rejected with 403.
Behaviour#
api.returning.ai doesn't serve this route yet: requests return an empty 404. Ask Returning.AI before you build on it.
Publishing makes the match visible to the traders in viewPermission, and to nobody else. It doesn't notify them. status becomes scheduled, open or locked from the clock, and version goes up by 1. This call has no body.
Before publishing, the draft is checked: the title and team names are set, the times are in order, kickoffAt is in the future, and viewPermission has at least one role or user, each still in your community. All problems come back together in details.
A published match can't go back to draft, and it can't be deleted through the API: it ends when you settle or void it. After publishing, only title, description, externalReference and later times can change.
Request#
Path parameters#
Rulemp_ and 24 hex characters
Eg"mp_66f000000000000000000801"
Headers#
curl --request POST \
--url https://api.returning.ai/v1/match-predictions/mp_66f000000000000000000801/publish \
--header 'Authorization: Bearer <API_KEY>'
Response#
A 200 returns the whole match prediction with isPublished true. Publishing a match that is already published returns 200 with its current state and changes nothing.
Rulesuccess
RuleMATCH_PREDICTION_PUBLISHED
X-Request-Id if you sent one, otherwise a generated req_... ID. Quote it when you contact support.Rulemp_ and 24 hex characters
.000.Ruleregulation or extra_time
correctResult when the called score is also exact.true when predicting costs coins.0 when enabled is false.draft until published. Then scheduled before predictionStartAt, open while traders can predict and locked from lockAt, all worked out from the clock. The rest follow a settle or void.Ruledraft, scheduled, open, locked, settlement_in_progress, settled, settlement_failed, void_in_progress, voided or void_failed
true once published.true while the match is open and the time is between predictionStartAt and lockAt.null here. Read the match with Get match prediction for its settlement totals.{
"meta": {
"status": "success",
"statusCode": 200,
"code": "MATCH_PREDICTION_PUBLISHED",
"requestId": "req_66f00000000000000000000000000811"
},
"message": "Match prediction published.",
"data": {
"id": "mp_66f000000000000000000801",
"title": "Australia vs New Zealand",
"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-10-01T08:00:00.000Z",
"lockAt": "2026-10-10T18:55:00.000Z",
"kickoffAt": "2026-10-10T19:00:00.000Z",
"scoreBasis": "regulation",
"viewPermission": {
"roleIds": ["66f000000000000000000806"],
"userIds": []
},
"rewards": {
"correctResult": {
"coins": 100,
"xp": 50
},
"exactScoreBonus": {
"coins": 200,
"xp": 100
}
},
"entryCost": {
"enabled": false,
"coins": 0
},
"status": "scheduled",
"isPublished": true,
"acceptingPredictions": false,
"attemptCount": 0,
"settlement": null,
"version": 2,
"createdAt": "2026-09-27T09:00:00.000Z",
"updatedAt": "2026-09-28T10:00:00.000Z",
"externalReference": "provider-fixture-123",
"description": "Predict the final score."
}
}
Errors#
Every error carries its code in meta.code and the request's ID in meta.requestId. Validation errors list each problem in details, with a field, code and message. The API key checks (401, 403, 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED) return detail and solution instead. A 404 with an empty body means the route isn't available on api.returning.ai yet. A 400 or 409 changes nothing.
Fix the request04
MATCH_PREDICTION_VALIDATION_FAILEDFix the requestviewPermission is empty (NO_TARGETS), kickoffAt has passed (KICKOFF_MUST_BE_FUTURE), or a role or user in viewPermission is no longer in your community (INVALID_REFERENCE). details lists each problem. Fix it with Patch match prediction; nothing changed.AUTHENTICATION_REQUIREDFix the requestAuthorization: Bearer <API_KEY> with a current Community API key.API_KEY_PERMISSION_DENIEDFix the requestmatchPredictions, or it is a personal key. Use a Community API key and add Match Prediction in Settings > Integration > API Keys.Fix the data03
MATCH_PREDICTION_NOT_FOUNDFix the datamp_... ID from Create match prediction or List match predictions.COMMUNITY_NOT_FOUNDFix the dataINVALID_LIFECYCLE_TRANSITIONFix the datasettled or voided, or it was moved out of draft while this request ran. Read it with Get match prediction.Retry with backoff05
VERSION_CONFLICTRetry with backoffRATE_LIMITEDRetry with backoffRetry-After, then retry.INTERNAL_ERRORRetry with backoffisPublished is true, you're done; otherwise publish again.AUTHENTICATION_FAILEDRetry with backoffMATCH_PREDICTION_FROZENRetry with backoff{
"meta": {
"status": "error",
"statusCode": 404,
"code": "MATCH_PREDICTION_NOT_FOUND",
"requestId": "req_66f00000000000000000000000000811"
},
"message": "Match prediction not found."
}