API Reference

Overview

The Playgent API allows you to programmatically generate and manage games. All API requests are made to:

https://api.playgent.com/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header:

curl -X POST https://api.playgent.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_API_KEY"

Creating an API Key

Go to Playgent CMS
Navigate to API in the top navigation
Click Create Key and give it a name
Copy your API key immediately - it won't be shown again!

Keep your API keys secure. Never expose them in client-side code or commit them to version control.

Endpoints

Generate Games

Generate one or more games from a topic or URL.

POST /api/v1/generate

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	The topic or URL to generate games from
`type`	string	Yes	Either `"topic"` or `"url"`
`game_types`	array or `"all"`	Yes	Game types to generate (see below)
`language`	string	No	Language code (default: `"en"`)
`date`	string	No	Date in `YYYYMMDD` format
`publish`	boolean	No	Auto-publish games (default: `true`)

Available Game Types

worday - Daily word puzzle
trivia - Quiz questions
memoji - Memory matching game
wordsearch - Word search puzzle
cluefinder - Clue-based puzzle
wordmaze - Word maze game
slider - Sliding tile puzzle
jigsaw - Jigsaw puzzle
facts - Did you know facts

Example: Generate from a Topic

curl -X POST https://api.playgent.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_API_KEY" \
  -d '{
    "prompt": "Lionel Messi",
    "type": "topic",
    "game_types": ["trivia", "worday", "memoji"],
    "language": "en"
  }'

Example: Generate from a URL

curl -X POST https://api.playgent.com/api/v1/generate \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_API_KEY" \
  -d '{
    "prompt": "https://www.nytimes.com/2024/01/15/technology/ai-news.html",
    "type": "url",
    "game_types": "all",
    "language": "en"
  }'

Response

{
  "thread_id": "api_1705312800000_abc123",
  "status": "completed",
  "publications": [
    {
      "game_type": "trivia",
      "content_id": "xYz789AbC",
      "title": "Lionel Messi Trivia",
      "status": "completed",
      "preview_url": "https://static.playgent.com/play?contentId=xYz789AbC"
    },
    {
      "game_type": "worday",
      "content_id": "aBc123XyZ",
      "title": "Lionel Messi Worday",
      "status": "completed",
      "preview_url": "https://static.playgent.com/play?contentId=aBc123XyZ"
    }
  ]
}

Response Fields

Field	Description
`thread_id`	Unique identifier for this generation batch
`status`	`"completed"`, `"partial"` (some failed), or `"failed"`
`publications`	Array of generated games
`publications[].game_type`	Type of game generated
`publications[].content_id`	Unique content identifier
`publications[].title`	Generated title for the game
`publications[].status`	`"completed"` or `"failed"`
`publications[].preview_url`	URL to preview/embed the game
`publications[].error`	Error message (if failed)

Update Publication

Update a publication's title, description, or publish status.

POST /api/v1/publications/:content_id/update

Request Body

Field	Type	Required	Description
`title`	string	No	New title for the game
`description`	string	No	New description
`published`	boolean	No	`true` to publish, `false` to unpublish

At least one field is required.

Example: Update Title

curl -X POST https://api.playgent.com/api/v1/publications/xYz789AbC/update \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_API_KEY" \
  -d '{
    "title": "Messi: The GOAT Quiz",
    "description": "Test your knowledge about the greatest footballer"
  }'

Example: Unpublish a Game

curl -X POST https://api.playgent.com/api/v1/publications/xYz789AbC/update \
  -H "Content-Type: application/json" \
  -H "x-api-key: pk_live_YOUR_API_KEY" \
  -d '{
    "published": false
  }'

Response

{
  "success": true,
  "content_id": "xYz789AbC",
  "title": "Messi: The GOAT Quiz",
  "description": "Test your knowledge about the greatest footballer",
  "published": true,
  "preview_url": "https://static.playgent.com/play?contentId=xYz789AbC"
}

Embedding Generated Games

For instructions on embedding games and advanced player options, see the Player SDK documentation.

Error Handling

The API uses standard HTTP status codes:

Status	Description
`200`	Success
`400`	Bad request (invalid parameters)
`401`	Unauthorized (missing or invalid API key)
`403`	Forbidden (key doesn't have access)
`404`	Not found
`500`	Server error

Error responses include a JSON body:

{
  "error": "Missing required field: prompt"
}

Rate Limits

API requests are rate limited based on your plan:

Plan	Rate Limit
Starter	100 requests/day
Pro	1,000 requests/day
Enterprise	Custom

Contact support@playgent.com for higher limits.

Code Examples

Node.js

const response = await fetch('https://api.playgent.com/api/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.PLAYGENT_API_KEY,
  },
  body: JSON.stringify({
    prompt: 'Taylor Swift',
    type: 'topic',
    game_types: ['trivia', 'memoji'],
    language: 'en',
  }),
});

const data = await response.json();
console.log(data.publications);

Python

import requests

response = requests.post(
    'https://api.playgent.com/api/v1/generate',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'pk_live_YOUR_API_KEY',
    },
    json={
        'prompt': 'Taylor Swift',
        'type': 'topic',
        'game_types': ['trivia', 'memoji'],
        'language': 'en',
    }
)

data = response.json()
print(data['publications'])

PHP

<?php
$ch = curl_init('https://api.playgent.com/api/v1/generate');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-api-key: pk_live_YOUR_API_KEY',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'prompt' => 'Taylor Swift',
        'type' => 'topic',
        'game_types' => ['trivia', 'memoji'],
        'language' => 'en',
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

print_r($data['publications']);

Support

Need help? Contact us at support@playgent.com or visit our documentation.

API Reference

On this page