REST API reference

Access

The preview is enabled per organization: ask for it from the contact page. Every response carries Gameheim-Api-Stability: preview. The user who connects needs the External apps (MCP & API) permission.

Base URL:

https://api.gameheim.com/api/v1

The full contract as OpenAPI 3.1, readable in any OpenAPI viewer: openapi.yaml.

Authentication

• OAuth 2.1, authorization code with PKCE (S256). Clients are public: no client secret.
• Register your app with a Client ID Metadata Document (your client_id is an https URL) or with dynamic client registration.
• Ask for the resource https://api.gameheim.com/api/v1. A token issued for the MCP server is refused here, and the other way round.
• The server metadata is published at https://api.gameheim.com/.well-known/oauth-authorization-server/api.
• Access tokens last one hour; refresh tokens rotate at every use, and a refresh token used twice closes the connection.

Conventions

Addressing

A project is its code (SKY) or its id. Tasks, bugs and decisions are their key (SKY-12, SKY-BUG-5, SKY-DEC-3) or their id. Keys change when a project’s code changes; ids never do, so store ids. Texts are Markdown.

Pagination

Lists return items and, when there is more, nextCursor: pass it back as cursor. limit goes up to 100.

Partial updates

PATCH changes only the fields sent; an empty string clears a text. If someone changed the same field since you read it, the answer is 409 FIELD_CONFLICT: read again and retry.

Idempotent creations

Send an Idempotency-Key with every creation and reuse it when you retry: the object is created once, and the retry gets the same answer. The same key with a different request is refused. Keys are remembered for 24 hours.

curl -X POST https://api.gameheim.com/api/v1/projects/SKY/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2d1e-build-4312" \
  -d '{"title": "Fix the save crash", "priority": "HIGH"}'

Limits

Per connection: 60 reads and 20 writes a minute, 200 creations a day, announced in RateLimit-Policy. Over a limit the answer is 429 with Retry-After.

No deletion

Nothing can be deleted through the API. The only DELETE removes the link between a bug and a task.

Errors

Errors are RFC 9457 problem details with a stable code to branch on.

HTTP/1.1 404
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Task not found",
  "code": "NOT_FOUND"
}

Endpoints

Paths are relative to the base URL. Parameters, bodies and responses are in the OpenAPI document.