API reference
Every endpoint of the public API v1, generated from the code.
This page is generated from the OpenAPI specification of the API. Download it to generate a client: /openapi/v1.json on your Maketools site. Start with the getting started guide.
Every request carries an organization API key: Authorization: Bearer dg_live_…. Only /api/v1/* accepts a key.
Endpoints
List forks
GET /api/v1/forks
Forks of the organization that owns the key (active and archived): title, status, visibility and deployed release. Never their configuration.
Required scope: forks:read
Response
| Field | Type | Required |
|---|---|---|
items |
api.PublicForkDto[] |
yes |
Get a fork
GET /api/v1/forks/{forkId}
One fork of the key’s organization. A fork of another organization is refused (403) and the attempt is audited.
Required scope: forks:read
Parameters
| Name | In | Type | Required |
|---|---|---|---|
forkId |
path | string | yes |
Response
| Field | Type | Required |
|---|---|---|
createdAt |
string | yes |
deployedReleaseNumber |
number | null | yes |
gameId |
string | yes |
id |
string | yes |
major |
number | yes |
slug |
string | yes |
sourceLocale |
common.ContentLocale |
yes |
status |
api.ForkStatus |
yes |
suspended |
boolean | yes |
title |
string | yes |
updatedAt |
string | yes |
visibility |
authz.ForkVisibility |
yes |
Export plays as CSV
GET /api/v1/forks/{forkId}/exports/csv
One row per play over the period (streamed). Each export is audited. Under k-anonymity the file only contains its header row and the response carries X-DG-Report-Suppressed: k-anonymity.
Required scope: reports:read
Parameters
| Name | In | Type | Required |
|---|---|---|---|
forkId |
path | string | yes |
from |
query | string | yes |
to |
query | string | yes |
groupId |
query | string | no |
Response
CSV file (text/csv, UTF-8).
Fork statistics
GET /api/v1/forks/{forkId}/stats
Same figures as the reports dashboard for a period (from and to are inclusive ISO days, 366 days at most). Players are pseudonymous unless the organization chose nominative reporting. With groupId, a group of fewer than 5 players returns suppressed: true and no figure (k-anonymity).
Required scope: reports:read
Parameters
| Name | In | Type | Required |
|---|---|---|---|
forkId |
path | string | yes |
from |
query | string | yes |
to |
query | string | yes |
groupId |
query | string | no |
Response
| Field | Type | Required |
|---|---|---|
avgScorePercent |
number | yes |
completionRate |
number | yes |
daily |
api.DailyStatDto[] |
yes |
passRate |
number | yes |
players |
api.PlayerStatDto[] |
yes |
plays |
number | yes |
reportingMode |
org.ReportingMode |
yes |
skills |
api.SkillStatDto[] |
yes |
suppressed |
boolean | yes |
uniquePlayers |
number | yes |
Errors
Errors are JSON objects { code, message, details: { code } } where details.code is stable: ERR_AUTH_REQUIRED (401: missing, malformed, revoked or expired key), ERR_ACCESS_DENIED (403: scope, organization or endpoint not allowed), ERR_NOT_FOUND (404), ERR_VALIDATION (400: invalid period), ERR_RATE_LIMITED (429: 120 requests per minute and per key).
Schemas
api.DailyStatDto
| Field | Type | Required |
|---|---|---|
avgScorePercent |
number | yes |
date |
string | yes |
plays |
number | yes |
api.ForkStatus
One of: active | archived
api.PlayerStatDto
| Field | Type | Required |
|---|---|---|
bestScorePercent |
number | yes |
lastPlayedAt |
string | yes |
passed |
boolean | yes |
playerLabel |
string | yes |
plays |
number | yes |
api.PublicForkDto
| Field | Type | Required |
|---|---|---|
createdAt |
string | yes |
deployedReleaseNumber |
number | null | yes |
gameId |
string | yes |
id |
string | yes |
major |
number | yes |
slug |
string | yes |
sourceLocale |
common.ContentLocale |
yes |
status |
api.ForkStatus |
yes |
suspended |
boolean | yes |
title |
string | yes |
updatedAt |
string | yes |
visibility |
authz.ForkVisibility |
yes |
api.SkillStatDto
| Field | Type | Required |
|---|---|---|
attempts |
number | yes |
correctRate |
number | yes |
skillId |
game.SkillId |
yes |
authz.ForkVisibility
One of: public | organization | restricted
common.ContentLocale
One of: en | fr | es | pt | de
game.SkillId
One of: prompting.context | prompting.constraints | prompting.examples | data.quality.duplicates | data.quality.missing | data.quality.formats | data.quality.outliers | ai.critical.hallucination | ai.critical.bias | ai.critical.verification | ai.usage.good-fit | ai.usage.personal-data | ai.usage.accountability | ai.usage.human-review | ai.usage.right-tool | data.leadership.incident | data.leadership.privacy | data.leadership.quality | data.leadership.value | data.leadership.culture | data.leadership.ai-adoption | ai.agents.data-access | ai.agents.tool-permissions | ai.agents.untrusted-content | ai.agents.efficiency | data.reading.charts | data.reading.causation | data.reading.sampling | data.reading.averages | data.reading.proportions
org.ReportingMode
One of: pseudonymous | nominative