---
url: /api.md
---
# Quickstart

The Klik Engine `/v1` API is the public, API-key-authenticated surface for
headless clients: autonomous "creator brains", CI pipelines, batch
generators, or any program that wants to drive game generation without a
browser session.

It is a **general creation contract**. On top of the free-text `prompt`, a
caller composes exactly the guidance it needs through layered fields
(`instructions`, `context`, `skills`, `settings`). Nothing is specific to
any one client - a persona-driven short-game brain and a CI regression
harness use the same endpoints.

## Base URL

| Environment | Base URL |
|---|---|
| Production | `https://ai.klikg.com` |
| Edge (internal dev) | `https://edgeai.klikg.com` |

All routes below are relative to the base URL.

## 1. Get an API key

Create a key in the lab under the **API Keys** tab:
[ai.klikg.com/lab](https://ai.klikg.com/lab). The full `sk-...` secret is
shown **exactly once** at creation time. See
[Authentication & keys](/api/authentication) for limits and management.

## 2. Create a project

```bash
curl -X POST https://ai.klikg.com/v1/projects \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Game", "template": "blank" }'
```

The response contains `data._id` - that is your `projectId`.

## 3. Submit a generation job

```bash
curl -X POST https://ai.klikg.com/v1/generate \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<projectId>",
    "prompt": "Build a one-button endless runner where you dodge falling blocks."
  }'
```

Response: `{ "jobId": "...", "status": "queued" }`.

::: tip Cold starts
The first job on an idle project cold-starts its engine container, which
can take up to ~2 minutes. During that window the endpoint returns
`503` with a retry hint - **retry every ~30 seconds** until it accepts.
:::

Only `projectId` and `prompt` are required. The
[creation contract](/api/creation-contract) documents the optional
`instructions`, `context`, `skills`, and `settings` fields that give you
precise control over the output.

## 4. Wait for completion

Poll status (does not consume quota):

```bash
curl https://ai.klikg.com/v1/generate/<jobId>/status?projectId=<projectId> \
  -H "Authorization: Bearer sk-..."
```

...or stream progress as Server-Sent Events from
`GET /v1/generate/<jobId>/events`. Terminal statuses are `completed`,
`failed`, and `cancelled`.

## 5. Download the game

```bash
curl -L -o game.zip \
  "https://ai.klikg.com/v1/generate/<jobId>/files?projectId=<projectId>" \
  -H "Authorization: Bearer sk-..."
```

The ZIP contains the files the job wrote - a complete, runnable web game.

## Next steps

* [Endpoints](/api/endpoints) - full request/response reference
* [The creation contract](/api/creation-contract) - `instructions`, `context`, `skills`, `settings`
* [Examples](/api/examples) - complete curl and Node.js flows
* [Errors & rate limits](/api/errors) - every status code and how to handle it