Overview

Framedash API (1.0)

The Framedash API provides programmatic access to game performance telemetry, project management, map management, content registry, analytics queries, data export, and player erasure.

Base URL

Every Web API path is relative to https://app.framedash.dev/api, so the full endpoint base is https://app.framedash.dev/api/v1. The /api prefix is required: requesting https://app.framedash.dev/v1/... (without /api) returns a 307 redirect to the HTML sign-in page rather than a JSON response. If you receive HTML instead of JSON, check that /api is present in the path.

Authentication

Requests authenticate with an API key sent via the X-API-Key header, or with an OAuth 2.1 Bearer access token (Authorization: Bearer ...) obtained via framedash login or a Connected app. When both headers are sent, X-API-Key takes precedence.

API keys can be generated from each project’s API Keys page in the Framedash dashboard. New keys use the neutral fd_ prefix; authorization is determined by the stored scope set, not by the prefix.

OAuth tokens can only carry the analytics:read and resources:write scopes; operations that require data:admin or events:write accept API keys only and declare ApiKeyAuth as their sole security scheme.

Response Format

Web API

Almost all Web API responses use the envelope:

{ "success": true, "data": { ... } }

Exception: POST /v1/maps/upload returns a flat body — the payload fields sit alongside success rather than nested under data:

{ "success": true, "mapId": "...", "action": "created" }

Error responses use RFC 9457 Problem Details, served as application/problem+json:

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Plan limit reached.",
  "error_category": "authorization",
  "retryable": false
}

Ingest API

The Event Ingestion endpoint (/v1/events) uses a different format:

{ "status": "accepted" }

• OpenAPI version: 3.1.0

Authentication

ApiKeyAuth

API key for authentication. Generate keys from each project’s API Keys page in the Framedash dashboard.

API key presets:

• Ingest (events:write) — SDK event ingestion only
• Read-only (analytics:read) — analytics and project reads
• Read & Write (analytics:read, resources:write) — read access plus resource changes
• Full (analytics:read, resources:write, data:admin) — raw SQL query, data export, and erasure

Security scheme type: apiKey

Header parameter name: X-API-Key

BearerAuth

OAuth 2.1 Bearer token obtained via framedash login (CLI) or a Settings -> Connected apps grant. OAuth tokens can only carry the analytics:read and resources:write scopes, so operations that require data:admin or events:write accept the X-API-Key scheme only and pin security accordingly.

Security scheme type: http