Overview

igts2B is a node-type driven iGaming translation platform that provides fast, consistent, and placeholder-safe localization for market, competitor, season, and related betting entities.

Production Base URL: https://igts2b.xyz Rules version field: 0.2.26

• Use GET /api/languages to load supported target languages.
• Use POST /api/excel/parse to normalize CSV/XLSX uploads.
• Use POST /api/process for real-time translation/transliteration.
• Use /api/jobs* only if async batch mode is required.

Authentication

All /api/* endpoints require auth except /api/health and /api/auth/login.

• Preferred: X-API-Key: <api_key>
• Optional: Authorization: Bearer <token>
• Do not send both headers together (400 ambiguous_auth).

API key scopes

Security

Enforced by platform

• API key active/revoked/expired validation.
• Scope-based access control per API key.
• IP whitelist enforcement (single IP and CIDR supported).
• Per-client-per-IP rate limiting.
• Prompt-injection and quality guard filters in translation pipeline.

Recommended for integrators

• Use dedicated API keys per environment.
• Rotate keys regularly and store in a secret manager.
• Use retry with exponential backoff for 429 and 5xx.
• Track error codes and latency in your observability stack.

Core Workflow

1. Authenticate using API key. Use X-API-Key for machine-to-machine integration and assign only required scopes.
2. Read language list from /api/languages. Validate target language values before submitting workload.
3. Parse files with /api/excel/parse when needed. This normalizes CSV/XLSX into API-ready items[].
4. Submit normalized records to /api/process. Use sync processing for low-latency, near-real-time flows.
5. Consume minimal output contract. In production, consume id + result_text, and log rules_version.

Implementation Notes

• Chunk large requests before sync processing (/api/process max 200 items).
• Preserve placeholders before and after translation.
• Retry only on 429 and 5xx.
• Do not retry 4xx validation errors; fix payload first.
• Log latency, HTTP status, error code, and rules_version for supportability.

Happy Path Example

1. GET /api/languages and validate target_lang.
2. POST /api/excel/parse (if source is spreadsheet).
3. POST /api/process and consume translated items.
4. Persist id, result_text, rules_version.

Error Path Example

1. Request with too many items returns 413 items_limit_exceeded.
2. Split payload and resubmit in chunks.
3. If throttled (429), backoff with jitter and retry.

Endpoint Reference

POST /api/process request

{
  "mode": "translation",
  "node_type": "bet_type_group",
  "target_lang": "pt-BR",
  "include_meta": false,
  "items": [
    { "id": "1001", "source_text": "First Goal Scorer" }
  ]
}

If you omit mode, the API returns 400 (for example: mode must be translation or transliteration).

entity_type is optional (advanced). Most integrations should only send node_type.

Excel Upload via API

Use POST /api/excel/parse to convert CSV/XLSX into normalized items[], then send those items to POST /api/process.

1. Convert the file to a full Data URL string (data:<mime>;base64,<payload>).
2. Send file_name, node_type, and file_data to /api/excel/parse.
3. Use the returned items directly in /api/process.

Auth rule: use exactly one method per request (X-API-Key or Authorization: Bearer ...). Do not send both.

FILE="bet_type_group.xlsx"
BASE64=$(base64 -i "$FILE" | tr -d '\n')

curl -sS -X POST https://igts2b.xyz/api/excel/parse \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "{
    \"file_name\":\"$FILE\",
    \"node_type\":\"bet_type_group\",
    \"file_data\":\"data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,$BASE64\"
  }"

`file_data` must include the data:...;base64, prefix. Raw base64 without prefix is invalid.

Node Mapping

Processing behavior is inferred from node_type. mode is required and selects translation vs transliteration.

Node Selection Cheat Sheet

To ensure the highest translation quality, integrators must send the correct node_type based on the nature of the content being translated.

The system does not guess entity intent. It relies on the provided node_type to select the appropriate processing pipeline.

Sending all content under a single node (for example always bet_type_group) may lead to reduced terminology accuracy.

How to Select the Correct Node

Note: Use node_type league for league and tournament names. Use mixed when one file contains competitor names, season labels, and standard/UI rows together. Processing behavior is selected by node_type; refer to the Node Mapping section for authoritative behavior.

Examples

Market Name
First Goal Scorer
Match Winner
Total Goals Over/Under

{
  "node_type": "bet_type_group"
}

Player / Team Name
Cristiano Ronaldo
Manchester United

{
  "node_type": "competitor"
}

Season
2024/2025
Spring Split

{
  "node_type": "season"
}

League / Tournament Name
Premier League

{
  "node_type": "league"
}

{
  "target_lang": "pt-BR",
  "items": [
    {
      "id": "L1",
      "result_text": "Premier League"
    }
  ]
}

Mixed Content File
FC Buxoro
2024/2025
Account Activity

{
  "node_type": "mixed"
}

Outcome Label
Anytime Scorer
First Half Winner
Yes / No

{
  "node_type": "outcome_value"
}

Important Notes

• The processing pipeline is selected based on node_type.
• Hybrid pipelines apply transliteration when needed.
• Standard pipelines apply terminology normalization.

Incorrect node selection may result in inconsistent translations, glossary misses, and incorrect name handling.

Best Practice

Integrators should map their internal entity types to IGTS node types before sending requests.

This ensures optimal translation quality across all supported languages.

Limits & Timeouts

HTTP Status Codes

Common Error Codes

Output Examples

POST /api/process (200, minimal output)

{
  "target_lang": "pt-BR",
  "rules_version": "0.2.26",
  "items": [
    {
      "id": "1001",
      "result_text": "Primeiro Marcador"
    }
  ]
}

POST /api/process (413, validation error)

{
  "ok": false,
  "error": "items_limit_exceeded",
  "message": "items exceeds sync limit (200). Use /api/jobs for larger batches.",
  "details": { "max_items": 200 }
}

POST /api/excel/parse (200, shape)

{
  "ok": true,
  "file_name": "bet_type_group.xlsx",
  "node_type": "bet_type_group",
  "summary": {
    "row_count": 430,
    "skipped_empty_value": 0
  },
  "items": [
    { "id": "1001", "source_text": "First Goal Scorer" }
  ]
}

cURL Samples

curl -sS https://igts2b.xyz/api/health

curl -sS https://igts2b.xyz/api/languages \
  -H "X-API-Key: YOUR_API_KEY"

curl -sS -X POST https://igts2b.xyz/api/process \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "mode":"translation",
    "node_type":"bet_type_group",
    "target_lang":"pt-BR",
    "items":[{"id":"1001","source_text":"First Goal Scorer"}]
  }'