Sports analytics and AI conversations for your business

Authentication and retries

The base URL is https://sportexa.online/api/partner/v1. Send requests from your server with Authorization: Bearer <token> and Accept: application/json. Set Content-Type: application/json for JSON requests. Keep the partner key on your server.

For session creation and follow-up actions, send an Idempotency-Key of up to 128 characters. Generate a unique key for each turn within your partner account. After a network failure, retry the same request with the same key.

Sessions and operations are scoped to the partner account that created them. Coverage is limited to agreed leagues and upcoming events in the calendar. Request limits depend on the access configuration.

Open a session

POST /sessions starts a preview of an upcoming match in a league enabled for your account. Replace the example ID 12345 with an available match ID.

curl https://sportexa.online/api/partner/v1/sessions \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: open-42-001' \
  -d '{"external_user_id":"customer-42","match_id":12345,"locale":"en"}'

• external_user_id is a stable user identifier from your platform, up to 128 characters. Use an internal ID in place of a name or email address.
• match_id is a positive integer. You can use match_query instead, with the full names of both participants, up to 200 characters.
• locale sets the language of the answer and actions. Use ru or en.
• bookmaker_id is an optional positive ID from the Sportexa catalog. Your account's configured bookmaker takes precedence.

A ready result returns HTTP 200 with the following structure.

{
  "session_id": "00000000-0000-4000-8000-000000000001",
  "operation_id": "00000000-0000-4000-8000-000000000002",
  "status": "ready",
  "answer_id": "00000000-0000-4000-8000-000000000002",
  "answer": "A short match preview.",
  "actions": [{"id": "why", "label": "Why?"}]
}

Continue the conversation

POST /sessions/{session_id}/messages accepts the answer_id from the latest answer and an action_id from its actions array. Use each action's label as the button text and refresh the buttons after every ready answer. Use why from the example only when it appears in the available actions.

curl "https://sportexa.online/api/partner/v1/sessions/${SESSION_ID}/messages" \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: followup-42-001' \
  -d "{\"answer_id\":\"${ANSWER_ID}\",\"action_id\":\"why\"}"

Check operation status

Standard mode returns previews synchronously. While a turn is still processing, the API returns HTTP 202 with status: processing, session_id and operation_id. Poll GET /sessions/{session_id}/operations/{operation_id} with the same Bearer token while processing continues. Stop polling after 200 or a terminal error. Asynchronous AI mode requires separate pilot approval. The mode is set on your account.

Errors

• 401 — the key is missing, invalid or revoked.
• 404 match_not_found — the match is unavailable or outside your enabled events.
• 409 match_ambiguous — choose a match_id from candidates and send a new request.
• 409 action_unavailable — the action is no longer available. Use the actions from the latest ready answer.
• 409 idempotency_conflict — the key is already associated with a different request.
• 422 — check the request fields.
• 429 — rate limit reached. Honor Retry-After when present.
• 503 — the operation failed or the preview is temporarily unavailable.

Issue a widget token from your backend

Send POST /api/partner/v1/widget-tokens with your partner key. Use the session creation fields and add the embedding page's origin. Its scheme, host and port must match the agreed website origin. Resolve external_user_id on your server from the user's authenticated session.

curl https://sportexa.online/api/partner/v1/widget-tokens \
  -H "Authorization: Bearer ${SPORTEXA_PARTNER_TOKEN}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id":"customer-42","match_id":12345,"locale":"en","origin":"https://partner.example"}'

The HTTP 201 response contains token and expires_at. Pass only the widget token to the browser. It is valid for one hour and scoped to the user, match and origin.

Load the script on a match page

In this example, widgetToken is the token from your backend. Use the same locale you used to issue the token.

<script src="https://sportexa.online/sportexa-widget.js"></script>
<script>
  const widget = window.SportexaWidget.mount({ token: widgetToken, locale: 'en' });
</script>

The preview starts when the user presses the widget button. For a different match, call widget.destroy() before remounting and request a new token. After expiry, request a new token to open a new chat. If your site restricts CSP, allow https://sportexa.online in script-src and frame-src.