Game Metadata API – v1

Base URL: {{ url('/v1') }}

Quick links

Authentication Pagination Errors Health Providers Games Mechanics Themes Tags Markets Account & Usage Rate limits

1. Authentication

All endpoints (except /v1/health) require the x-api-key header.

GET {{ url('/v1/providers') }}
x-api-key: YOUR_API_KEY

Invalid or missing key returns 401:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key."
  }
}

2. Versioning

Version prefix in URL (e.g., /v1). Future versions may alter payloads.

3. Pagination

List endpoints accept page and page_size (default 1 and 50; max 200). Laravel Resource collections return pagination links and meta.

GET {{ url('/v1/providers?page=2&page_size=20') }}
x-api-key: YOUR_API_KEY

Example response (truncated):

{
  "data": [ { "code": "netent", "name": "NetEnt", "website_url": "https://www.netent.com" } ],
  "links": { "first": "...", "last": "...", "prev": "...", "next": "..." },
  "meta": { "current_page": 2, "from": 21, "last_page": 4, "path": "{{ url('/v1/providers') }}", "per_page": 20, "to": 40, "total": 80 }
}

4. Errors

Standardized error shape:

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human readable explanation.",
    "details": {"optional": "context"}
  }
}

5. Health

GET /v1/health

No authentication required.

{
  "status": "ok",
  "uptime_seconds": 123456,
  "version": "v1"
}

6. Providers

GET /v1/providers

List providers (paginated).

curl -H "x-api-key: YOUR_API_KEY" "{{ url('/v1/providers?page=1&page_size=50') }}"

{
  "data": [
    { "code": "netent", "name": "NetEnt", "website_url": "https://www.netent.com" }
  ],
  "links": { ... },
  "meta": { ... }
}

GET /v1/providers/{providerCode}

curl -H "x-api-key: YOUR_API_KEY" "{{ url('/v1/providers/netent') }}"

{
  "data": { "code": "netent", "name": "NetEnt", "website_url": "https://www.netent.com" }
}

7. Games

Filters: provider, type, q, rtp_min, rtp_max, volatility, max_win_min, reels/rows/lines min/max, has_free_spins, has_bonus_buy, has_jackpot, mechanic[], theme, tag[], market; sort by name|rtp|max_win|release_date asc/desc.

GET /v1/games

curl -H "x-api-key: YOUR_API_KEY" "{{ url('/v1/games?provider=netent&rtp_min=96&sort=rtp_desc&page=1&page_size=20') }}"

{
  "data": [
    {
      "id": 123,
      "provider": { "code": "netent", "name": "NetEnt" },
      "type": "slot",
      "name": "Starburst",
      "slug": "starburst",
      "rtp_default": 96.09,
      "volatility": "LOW",
      "max_win_x": 600.0,
      "reels": 5,
      "rows": 3,
      "lines_or_ways": 10,
      "has_free_spins": false,
      "has_bonus_buy": false,
      "has_jackpot": false,
      "theme": { "code": "space", "name": "Space" },
      "mechanics": [ { "code": "EXPANDING_WILDS", "name": "Expanding Wilds" } ],
      "tags": [ { "code": "classic", "name": "Classic" } ],
      "release_date_global": "2013-01-01",
      "thumbnail_url": "https://cdn.example.com/starburst-thumb.png",
      "demo_url": "https://demo.example.com/starburst"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

GET /v1/games/{id}

curl -H "x-api-key: YOUR_API_KEY" "{{ url('/v1/games/123') }}"

{
  "data": {
    "id": 123,
    "provider": { "code": "netent", "name": "NetEnt", "website_url": "https://www.netent.com" },
    "type": "slot",
    "name": "Starburst",
    "slug": "starburst",
    "code": "starburst_code",
    "rtp_default": 96.09,
    "rtp_configs": [ { "name": "default", "rtp": 96.09 } ],
    "volatility": "LOW",
    "original_volatility_text": "Low",
    "max_win_x": 600.0,
    "reels": 5,
    "rows": 3,
    "lines_or_ways": 10,
    "min_bet": 0.1,
    "max_bet": 100.0,
    "has_free_spins": false,
    "has_bonus_buy": false,
    "has_jackpot": false,
    "theme": { "code": "space", "name": "Space" },
    "subtheme": "Gems in space",
    "mechanics": [ { "code": "RESPINS", "name": "Respins" } ],
    "tags": [ { "code": "classic", "name": "Classic" } ],
    "markets": [ { "code": "MGA", "name": "Malta Gaming Authority", "availability": "AVAILABLE" } ],
    "release_date_global": "2013-01-01",
    "thumbnail_url": "https://cdn.example.com/starburst-thumb.png",
    "background_url": null,
    "demo_url": "https://demo.example.com/starburst",
    "short_description": "A classic low-volatility slot...",
    "long_description": "Starburst is a classic NetEnt slot...",
    "created_at": "2025-01-01T12:00:00Z",
    "updated_at": "2025-01-01T12:00:00Z"
  }
}

GET /v1/providers/{providerCode}/games/{slug}

curl -H "x-api-key: YOUR_API_KEY" "{{ url('/v1/providers/netent/games/starburst') }}"

Returns same payload as /v1/games/{id}.

GET /v1/games/search

Same filters as /v1/games. Intended for fuzzy/semantic search of q.

8. Mechanics

GET /v1/mechanics

{
  "data": [ { "code": "AVALANCHE", "name": "Avalanche", "description": "Symbols fall into place..." } ],
  "links": { ... },
  "meta": { ... }
}

9. Themes

GET /v1/themes

{
  "data": [ { "code": "space", "name": "Space" } ],
  "links": { ... },
  "meta": { ... }
}

10. Tags

GET /v1/tags

{
  "data": [ { "code": "classic", "name": "Classic" } ],
  "links": { ... },
  "meta": { ... }
}

11. Markets

GET /v1/markets

{
  "data": [ { "code": "MGA", "name": "Malta Gaming Authority", "region": "EU" } ],
  "links": { ... },
  "meta": { ... }
}

12. Account & Usage

GET /v1/me

{
  "client_id": "cl_123",
  "name": "Example Affiliate",
  "plan": { "code": "PRO", "name": "Pro", "daily_request_limit": 10000, "monthly_request_limit": 300000 }
}

GET /v1/me/usage

{
  "period": { "from": "2025-01-01", "to": "2025-01-07" },
  "daily": [ { "date": "2025-01-01", "total_requests": 1234 } ]
}

13. Rate limiting

On breach, API responds with 429:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for plan PRO: 10000 requests per day."
  }
}

14. Error samples

Status	When	Body
400 / 422	Validation	`{ "error": {"code": "BAD_REQUEST", "message": "Validation failed.", "details": {"field": ["message"]}} }`
401	Missing/invalid key	`{"error": {"code": "UNAUTHORIZED", "message": "Missing or invalid API key."}}`
403	Forbidden	`{"error": {"code": "FORBIDDEN", "message": "Forbidden."}}`
404	Not found	`{"error": {"code": "NOT_FOUND", "message": "Resource not found."}}`
429	Rate limit	`{"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "..."}}`
500	Server error	`{"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred."}}`

Copied