# HomeGame24 Integration API — agent & developer guide

Use this when building integrations, automations, or when an AI tool needs to call HomeGame24 programmatically.

## Endpoints

| Resource | URL |
|----------|-----|
| API base | `https://api.homegame24.com/v1` |
| Live OpenAPI | `https://api.homegame24.com/v1/openapi.json` |
| Static OpenAPI mirror | `https://homegame24.com/openapi/v1.json` |
| Human docs UI | `https://homegame24.com/docs/api` |
| Agent index | `https://homegame24.com/llms.txt` |

## Authentication

1. In the HomeGame24 panel, open **API Keys**
2. Create a key (`pk_…`) with the **minimum scopes** required
3. Send on every request:

```http
Authorization: Bearer pk_…
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
```

## Conventions

- Responses follow **JSON:API 1.1** (`data`, `attributes`, `relationships`, `links`, `meta`)
- List endpoints support cursor pagination (`links.next`, `meta.nextCursor`)
- Prefer the OpenAPI document for schemas, enums, and examples — do not invent fields

## Main resource areas

- **Players** — roster identities used at tables
- **Player Groups** — access bundles attachable to sessions
- **Wallets / wallet operations** — play-money chip balances and movements
- **Game Sessions** — live runs of configured games (the thing players join)

Exact paths and payloads: see OpenAPI tags and operationIds.

## Rate limits

- Authenticated `/v1` requests: **120 requests per 60 seconds** per API key
- Enforced per Cloudflare location / PoP
- `GET /v1/openapi.json` is not rate limited
- On exceed: HTTP **429** with `Retry-After` and `X-RateLimit-Limit`

## Recommended agent workflow

1. Fetch OpenAPI (`/v1/openapi.json`)
2. Confirm required scopes for the planned operations
3. Create or resolve Players (and Groups if needed)
4. Ensure wallet/chip state is valid for buy-in
5. Create a Game Session for an existing game configuration
6. Return the play/session identifiers to the host or embedding app
7. For host UX guidance (panel clicks), also read `/guides/run-a-poker-session.md`

## Example agent task: "Set up tonight's home game via API"

```
1. GET /v1/players — list existing roster
2. POST /v1/players — create any missing players
3. POST /v1/player-groups — optional access group
4. Wallet ops per OpenAPI — ensure chip balances for buy-in
5. POST /v1/game-sessions — create session for game_id X
6. Return session play link / identifiers to the host
```

Always read OpenAPI for exact attribute names and required relationships.

## Safety / product constraints

- HomeGame24 hosts **social / play-money** poker — not casino cash wagering
- Do not instruct users to treat chip balances as withdrawable cash
- Hosting charges are separate prepaid credits for engine/server time

## Support

- Human contact: https://homegame24.com/contact
- Email: support@homegame24.com