Partner API Reference

This page documents the API endpoints available to PlayRen partners for managing their game catalog.

Authentication

All partner API requests require a Bearer token in the Authorization header:

Authorization: Bearer {your-partner-api-key}

API keys are provided during partner onboarding. Keep your key secure and never expose it in client-side code.

Base URL

https://play.ren.bd/api/partners

Endpoints

List Games

Retrieve all games in your partner catalog.

GET /api/partners/games

Response:

{
  "games": [
    {
      "id": "clx1234...",
      "slug": "garden-of-forking-paths",
      "title": "The Garden of Forking Paths",
      "developer": "Starlight Studio",
      "tags": ["Visual Novel", "Romance"],
      "status": "active",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-03-01T14:00:00Z"
    }
  ],
  "total": 1
}

Get Game Details

Retrieve full metadata for a specific game.

GET /api/partners/games/{slug}

Response:

{
  "id": "clx1234...",
  "slug": "garden-of-forking-paths",
  "title": "The Garden of Forking Paths",
  "developer": "Starlight Studio",
  "description": "A branching narrative adventure...",
  "tags": ["Visual Novel", "Romance", "Mystery"],
  "launcher": "garden-of-forking-paths.sh",
  "renpyDir": "GardenOfForkingPaths-1698234567",
  "thumbnail": "https://storage.example.com/cover.jpg",
  "status": "active",
  "cacheStatus": {
    "servers": 3,
    "cached": 2
  }
}

Register a New Game

Add a new game to your catalog.

POST /api/partners/games
Content-Type: application/json

Request body: See Game Metadata for all available fields.

Response (201 Created):

{
  "id": "clx5678...",
  "slug": "my-new-game",
  "status": "pending_upload"
}

Update Game Metadata

Update metadata for an existing game.

PATCH /api/partners/games/{slug}
Content-Type: application/json

Only include the fields you want to change. Omitted fields are not modified.

Upload Game Files

Upload a tar.gz archive containing the game.

PUT /api/partners/games/{slug}/upload
Content-Type: application/gzip

Send the archive as the raw request body. See Adding Games for packaging instructions.

Response:

{
  "status": "ok",
  "slug": "my-new-game",
  "size": 524288000,
  "checksum": "sha256:abc123..."
}

Check Sync Status

Check the distribution status of a game across game servers.

GET /api/partners/games/{slug}/sync

Response:

{
  "slug": "garden-of-forking-paths",
  "totalServers": 4,
  "cachedOn": 3,
  "pendingSync": 1,
  "servers": [
    { "id": "srv-01", "status": "cached", "cachedAt": "2025-03-01T12:00:00Z" },
    { "id": "srv-02", "status": "cached", "cachedAt": "2025-03-01T12:05:00Z" },
    { "id": "srv-03", "status": "cached", "cachedAt": "2025-03-01T12:10:00Z" },
    { "id": "srv-04", "status": "pending", "cachedAt": null }
  ]
}

Delete a Game

Remove a game from your catalog. Active sessions are not interrupted, but no new sessions can be started.

DELETE /api/partners/games/{slug}

Response (204 No Content)

Rate Limits

Partner API endpoints are rate-limited to 100 requests per minute per API key. Upload endpoints have a separate limit of 10 uploads per hour.

If you exceed the limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Error Responses

All errors follow a consistent format:

{
  "error": "not_found",
  "message": "Game with slug 'xyz' not found"
}

See Error Codes for a complete list.

Next Steps

• Game Metadata — Required fields for game registration.
• Adding Games — Packaging and upload instructions.