Developer API
REST reference for developer keys, models, projects, usage, billing providers, and Network Overview dashboard data (BFF).
Overview#
The Developer API provides endpoints for developers to manage API keys, browse available AI models, organize projects, and track usage. Keys are linked to billing providers through a brokered provider login flow.
Authentication
/api/v1/developer/*— requires an authenticated session (JWT), except where individual routes state otherwise.GET /api/v1/billing-providers— public (catalog only).GET /api/v1/dashboard/*— public read-only JSON used by the Network Overview (landing page/and/dashboard); see below.
For how overview data is aggregated (facade, upstream metrics API, subgraph), see Dashboard data architecture.
Network overview data (dashboard BFF)#
These routes back the Network Overview UI (OverviewContent): the public home page loads them directly; the authenticated dashboard usually receives the same fields via the dashboard provider plugin (GraphQL over the event bus), while the HTTP surface stays the source of truth for caching and public access.
Responses are JSON. Shapes align with the dashboard types in @naap/plugin-sdk (for example DashboardKPI, DashboardPipelineUsage, DashboardOrchestrator, JobFeedEntry). Failed upstream calls often return 503 with { "error": { "code", "message" } } (job feed returns an empty streams array and flags instead).
| Route | Role in overview |
|---|---|
GET /api/v1/dashboard/kpi | KPI tiles, hourly usage charts |
GET /api/v1/dashboard/pipelines | Pipeline usage table |
GET /api/v1/dashboard/pipeline-catalog | Pipeline / model catalog rows |
GET /api/v1/dashboard/orchestrators | Orchestrator table |
GET /api/v1/dashboard/protocol | Protocol stats strip |
GET /api/v1/dashboard/gpu-capacity | GPU capacity section |
GET /api/v1/dashboard/pricing | Per-pipeline pricing and capacity hints |
GET /api/v1/dashboard/fees | Fees / volume chart |
GET /api/v1/dashboard/job-feed | Live job list |
GET /api/v1/dashboard/kpi#
| Query | Description |
|---|---|
timeframe | Window length in hours (string/number). Clamped to 1–168. Default 24 if omitted. |
pipeline | Optional — filter KPI to a pipeline id. |
model_id | Optional — filter KPI to a model id. |
GET /api/v1/dashboard/pipelines#
| Query | Description |
|---|---|
timeframe | Same hour-based window as KPI (passed through to the metrics API). |
limit | Max pipelines (default 5; the overview uses 200). |
GET /api/v1/dashboard/pipeline-catalog#
No query parameters.
GET /api/v1/dashboard/orchestrators#
| Query | Description |
|---|---|
period | Period string such as 12h, 24h — must match the overview timeframe (UI maps selected hours to ${hours}h). Default 24h. |
GET /api/v1/dashboard/protocol#
No query parameters.
GET /api/v1/dashboard/gpu-capacity#
| Query | Description |
|---|---|
timeframe | Same hour-based selection as KPI (resolver normalizes the key). |
GET /api/v1/dashboard/pricing#
No query parameters.
GET /api/v1/dashboard/fees#
| Query | Description |
|---|---|
days | History length for fee/volume series. Optional; default 180. If set, must be an integer 7–365. |
GET /api/v1/dashboard/job-feed#
| Query | Description |
|---|---|
pollMs | Client poll interval in milliseconds; used to key Cache-Control max-age so CDN/browser caching matches refresh cadence (overview uses values such as 5000, 15000, 30000, 90000). |
refresh=1 or nocache=1 | Bypass cache for a one-off refetch. |
Response (success): { "streams": JobFeedEntry[], "clickhouseConfigured": boolean, "queryFailed": boolean } — when the upstream query fails, streams is empty and queryFailed is true.
Overview timeframe values#
The overview timeframe control uses hour strings 1, 6, 12, 18, 24, 48, 72, 168 (7d). Pass the same value as timeframe on KPI, pipelines, and GPU capacity, and derive period for orchestrators as ${hours}h.
Billing Providers#
List Providers#
GET /api/v1/billing-providersReturns the catalog of enabled billing providers. No authentication required.
Response:
| 1 | { |
| 2 | "success": true, |
| 3 | "data": { |
| 4 | "providers": [ |
| 5 | { |
| 6 | "id": "bp_xxx", |
| 7 | "slug": "livepeer", |
| 8 | "displayName": "Livepeer", |
| 9 | "description": "Decentralized video infrastructure", |
| 10 | "icon": "video", |
| 11 | "authType": "oauth" |
| 12 | } |
| 13 | ] |
| 14 | } |
| 15 | } |
| Field | Type | Description |
|---|---|---|
slug | string | URL-safe identifier |
displayName | string | Human-readable name |
authType | string | Authentication method (oauth, api_key) |
API Keys#
List Keys#
GET /api/v1/developer/keysReturns the current user's API keys with pagination.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 1 | Page number |
pageSize | number | 20 | Results per page |
Response Fields:
| Field | Type | Description |
|---|---|---|
keys[].id | string | Key ID |
keys[].keyPrefix | string | First few characters of the key (for identification) |
keys[].label | string | Optional user-provided label |
keys[].status | string | Key status (ACTIVE, REVOKED) |
keys[].project | object | Associated project (id, name, isDefault) |
keys[].billingProvider | object | Linked billing provider (id, slug, displayName) |
keys[].createdAt | string | Creation timestamp |
Create Key#
POST /api/v1/developer/keysCreate a new API key linked to a billing provider. The raw key is returned only once in the response.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
billingProviderId | string | Yes | ID of the billing provider |
rawApiKey | string | Yes | The provider-issued API key (obtained through OAuth) |
projectId | string | No | Existing project ID |
projectName | string | No | Create a new project with this name |
label | string | No | Human-readable label for the key |
If neither projectId nor projectName is provided, the key is assigned to the user's default project.
Response:
| 1 | { |
| 2 | "success": true, |
| 3 | "data": { |
| 4 | "key": { "id": "...", "keyPrefix": "sk-...", "status": "ACTIVE" }, |
| 5 | "rawApiKey": "sk-xxxxx", |
| 6 | "warning": "Store this key securely. It will not be shown again." |
| 7 | } |
| 8 | } |
Get / Delete Key#
GET /api/v1/developer/keys/{id}
DELETE /api/v1/developer/keys/{id}Retrieve details or revoke a specific API key.
AI Models#
List Models#
GET /api/v1/developer/modelsReturns available AI models from the database.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
type | string | Filter by model type (e.g., text, image, video) |
featured | boolean | Only show featured models (true) |
realtime | boolean | Only show realtime-capable models (true) |
Get Model#
GET /api/v1/developer/models/{id}Returns details for a specific AI model.
Network Models#
GET /api/v1/developer/network-modelsReturns models available on the decentralized network with pricing and availability information.
Projects#
List Projects#
GET /api/v1/developer/projectsReturns the current user's projects. Each user has a default project created automatically.
Usage#
Get Usage#
GET /api/v1/developer/usageReturns API usage statistics for the current user's keys.
OAuth Flow#
API keys are typically created through a billing provider OAuth flow:
- User selects a billing provider from the catalog (
GET /api/v1/billing-providers) - User is redirected to the provider's OAuth consent page
- Provider redirects back with an authorization code
- NaaP exchanges the code for a provider-issued API key
- The key is stored via
POST /api/v1/developer/keys
The OAuth session is tracked in the BillingProviderOAuthSession table.
Related Resources#
- Admin Operations — Platform admin APIs
- Service Gateway API Keys — Gateway-specific API keys (
gw_prefix)