Getting started with the API

The Maketools public API lets your tools (BI dashboard, LMS, data warehouse) read the reports of your forked games without anyone signing in. It is read-only and versioned under /api/v1/. It is included in the Pro and Enterprise plans.

1. Create an API key

Owners and admins (with two-step verification) create keys in Organisation → API keys:

1. Choose a name that says where the key will be used (for example Power BI).
2. Choose its scopes, and nothing more than what the tool needs:
   • forks:read: list the forks of the organisation and read their status;
   • reports:read: read the statistics of a fork and export its plays as CSV.
3. Optionally set an expiration date. Prefer keys that expire, and rotate them.

The key looks like dg_live_<id>_<secret>. It is shown only once: copy it into your tool's secret store right away. Maketools only keeps a hash of the secret and cannot show it again. A lost key is revoked and replaced.

2. Call the API

Send the key in the Authorization header of every request:

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" \
  "https://<your-maketools-site>/api/v1/forks"

Then read the statistics of a fork over a period (inclusive ISO days, 366 days at most):

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" \
  "https://<your-maketools-site>/api/v1/forks/<forkId>/stats?from=2026-09-01&to=2026-09-30"

Or export its plays as CSV:

curl -H "Authorization: Bearer $MAKETOOLS_API_KEY" -o plays.csv \
  "https://<your-maketools-site>/api/v1/forks/<forkId>/exports/csv?from=2026-09-01&to=2026-09-30"

Every endpoint, its parameters and its response are listed in the API reference, generated from the code. The OpenAPI specification is served at /openapi/v1.json to generate a client.

What a key can do

• A key only works on /api/v1/*. Any other endpoint refuses it (403).
• A key only sees its organisation. Asking for a fork of another organisation is refused (403), and the attempt is written to your audit log.
• A key never writes anything, never plays a game and never sees the configuration of a fork.
• Reports follow the same rules as the dashboard: players are pseudonymous unless your organisation chose nominative reporting, and a group of fewer than 5 players is never detailed.
• Each key may send 120 requests per minute; beyond that the API answers 429 (ERR_RATE_LIMITED).

Security and audit

• Creating and revoking a key, and every refused use of a key (wrong secret, revoked or expired key, insufficient scope, other organisation, endpoint outside /api/v1/*), are recorded in the organisation's audit log.
• Revoke a key as soon as it is no longer needed or may have leaked: it stops working immediately. The list shows when each key was last used.
• If your organisation moves below the Pro plan, its keys stop working; they can still be listed and revoked.