API Overview

Base URL, authentication modes, response envelope, errors, and credit/rate-limit behavior for the GMC REST API.

Base URL

All endpoints are versioned under:

https://gamemarketcopilot.com/api/v1

Authenticated access (API key or CLI credential) requires a plan with API access; Starter and Pro include it, and complimentary grants can enable it too. Anonymous callers can still reach most read endpoints and get a limited public preview: results are capped and some fields come back locked or redacted rather than omitted, so the shape of the response stays stable. See /plans for what each plan unlocks.

Authentication

The API accepts a bearer token on every request:

Authorization: Bearer <token>

Three token types exist, and they are not interchangeable:

1. API key (gmc_...). Created in the GMC dashboard under Settings -> API. The secret is shown once at creation time; store it in a secrets manager or CI variable. Best for CI, headless jobs, and server-to-server integrations.
2. CLI credential (gmcc_...). Minted by the browser OAuth flow that runs when you execute gmc login (see /cli). Best for local development, since it is short-lived and tied to a browser session rather than a long-lived secret you have to manage.
3. MCP OAuth token. Issued to MCP clients and scoped to the MCP endpoint only. It is rejected by this REST API: MCP callers use the MCP protocol surface, not /api/v1/... directly. See /agents/mcp.

The browser app itself does not use any of the above. Copilot chat, chart generation, and export endpoints are authenticated by browser session cookies and are not part of this bearer-token API contract, so they cannot be called with an API key or CLI credential.

Response envelope

Every successful response is a JSON object with the same top-level shape (pagination and warnings appear only when relevant):

{
  "data": {},
  "meta": {
    "requestId": "req_...",
    "generatedAt": "2026-01-01T00:00:00.000Z"
  },
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1234,
    "nextOffset": 20
  },
  "warnings": []
}

• data is the payload; its shape is endpoint-specific and defined in the OpenAPI contract.
• meta always includes requestId (useful when reporting an issue) and generatedAt. Depending on the endpoint it may also carry entitlement, taxonomy, translation, or timing information.
• pagination is present on list endpoints and uses offset/limit paging: send limit and offset on the request, read total and nextOffset (when present) from the response to fetch the next page.
• warnings is present when the server wants to flag something short of an error, such as a partially degraded data source.

Errors

REST API errors use a single envelope with a stable, machine-readable code (MCP tool errors have their own, flatter shape defined by the MCP protocol). The codes below are the ones you are most likely to see; the API can return others for edge cases:

{
  "error": {
    "code": "INVALID_TAG",
    "message": "Unknown tags: foo. Search valid tags at GET /api/v1/tags.",
    "param": "tags",
    "requestId": "req_..."
  }
}

Stable error codes:

Credits and rate limits

Every call is priced in credits. Charges are itemized on the usage screen in the GMC dashboard, current usage and your remaining allowance are available from /api/v1/status, and MCP tool responses additionally include the exact charge in their metadata. The API does not publish a fixed per-endpoint price list on this site because pricing evolves with the product; the cost model instead groups endpoints into a small number of cost classes:

• Free: workspace and metadata operations that don’t touch market data, such as checking status or listing tags, cost nothing.
• Baseline: simple reads, like fetching one game’s detail, are the cheapest metered calls.
• Counts and small aggregates: cost a bit more than a baseline read, reflecting the larger scan behind the answer.
• Per-title synthesis: endpoints that synthesize review or marketing analysis for a single title cost several times the baseline rate, since they combine and summarize a large amount of underlying data.
• Heavy aggregate analysis: cohort-level and cross-title benchmark endpoints that scan and synthesize across many games cost the most.

Two distinct things can produce an HTTP 429, and both include a Retry-After header (seconds):

• RATE_LIMITED: you’re calling too fast in a short window. Back off for the given Retry-After and retry.
• QUOTA_EXCEEDED: your workspace’s monthly credit allowance is used up. Retry-After reflects the time until the allowance resets; the practical fix is to upgrade plan or wait for reset. See /plans.

See /troubleshooting if you’re hitting either case unexpectedly.

Contract sources

This page and /api/endpoints describe behavior that applies across the API. They intentionally do not restate endpoint-by-endpoint parameters, fields, or request/response schemas. The OpenAPI document is the authoritative, machine-readable contract for that level of detail:

• Interactive reference: gamemarketcopilot.com/api-docs
• Machine-readable OpenAPI document: gamemarketcopilot.com/api/v1/openapi
• Endpoint catalog (capability discovery): gamemarketcopilot.com/api/v1/schema
• Tag taxonomy: gamemarketcopilot.com/api/v1/tags

Next steps

• Browse endpoint families: /api/endpoints
• Use the API from a terminal: /cli
• Use the API from an agent over MCP: /agents/mcp