Endpoints

All endpoints are relative to the base URL (https://ai.klikg.com) and require authentication.

POST /v1/projects

Create a project owned by the key's user. An autonomous client typically creates one project per game.

Request body:

{ "name": "My Game", "template": "blank", "description": "optional" }

Response 201:

{ "success": true, "data": { "_id": "<projectId>", "name": "My Game" } }

data._id is the projectId used by every other endpoint.

POST /v1/generate

Submit a generation job. Cold-starts the project's engine container if it is not already running - a cold start can take up to ~2 minutes, during which the endpoint returns 503 with a retry hint (retry every ~30 s).

Request body (only projectId and prompt are required):

{
  "projectId": "<24-hex project id>",
  "prompt": "Build a one-button endless runner where you dodge falling blocks.",
  "instructions": "Persistent direction: bold flat-color art, punchy game feel, 30-60s shorts.",
  "context": [
    { "name": "research", "content": "Endless runners peak retention with a 3-second failure-restart loop..." }
  ],
  "skills": [
    {
      "key": "one-button-runner",
      "title": "One-button runner core loop",
      "prompt": "endless runner, tap to jump",
      "mechanics": ["gravity", "obstacle spawn", "score on distance"],
      "engine": "phaser",
      "files": [
        { "path": "src/scenes/GameScene.js", "content": "// proven code ..." }
      ]
    }
  ],
  "settings": {
    "gameType": "klik-short",
    "model": "openrouter/claude-fable-5",
    "reasoningLevel": "medium",
    "dimensionMode": "2d",
    "aiImages": true,
    "aiAudio": true,
    "visualQaActive": true
  }
}

Every optional field is documented in The creation contract.

Response 200:

{ "jobId": "<jobId>", "projectId": "<projectId>", "status": "queued", "sessionId": "<sessionId>" }

This is the only endpoint that counts against per-key quotas.

GET /v1/generate/:jobId/status

Poll job status. The response mirrors the engine's job record (status, progress, and so on). Statuses progress through queued / running to a terminal completed, failed, or cancelled. Polls consume no quota.

GET /v1/generate/:jobId/events

Server-Sent Events stream of the job's progress - the same event stream the IDE consumes (assistant text, tool calls, build results, completion). Reconnect-friendly; polling status is the simpler alternative.

GET /v1/generate/:jobId/files

Download a ZIP of the files written by the job. Available once the job is completed or failed.

DELETE /v1/generate/:jobId

Cancel a running job.

Pass projectId on follow-up calls

Follow-up routes (status, events, files, DELETE) resolve the job's container from an in-memory route table recorded at submission. After a gateway restart that table is empty - always pass ?projectId=<id> on these calls so the gateway can re-resolve the container. It is harmless when not needed and makes clients restart-proof.