API Reference
Complete reference for all Ingate REST API endpoints. Organized by domain: proxy, prompts, evals, datasets, playground, sessions, usage, organizations, auth, and system.
Base URL
https://api.ingateai.com. Include your API key in the X-Ingate-Key header with every request. Dashboard sessions may use Authorization: Bearer <token> instead.API Versioning
/api/* routes use the /api/v1/ prefix. The proxy wildcard route (POST /*) is the only exception. It matches any path not claimed by Ingate's own routes.API Groups
Proxy API
Route requests to any LLM provider with logging, fallback, caching, and format translation.
Prompts API
Create, version, and render prompt templates with variable interpolation and rollback.
Evals API
Define evaluations, trigger runs against datasets, and query scored results.
Datasets API
Manage versioned datasets with test cases for evaluations and playground experiments.
Playground API
Run completions, compare models side-by-side, and save prompt versions from the playground.
Usage & Cost API
Query token usage summaries, cost breakdowns by provider/model, and time-series analytics.
Plus Sessions & Users, Organizations, Auth & Keys, and System See full endpoint tables below.
Proxy API
The proxy is the core of Ingate. Any request to a path not claimed by Ingate's own routes is forwarded to the target provider. Set X-Ingate-Provider to choose the destination.
| Method | Path | Description |
|---|---|---|
| POST | /* | Proxy request to the configured provider. Supports streaming, fallback chains, caching, and format translation via headers. |
Prompts API
Versioned prompt templates with variable interpolation. Each update creates a new immutable version. Render any version on-demand.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/prompts | Create a new prompt template |
| GET | /api/v1/prompts | List all prompts (paginated, filterable) |
| GET | /api/v1/prompts/:ns/:slug | Get prompt by namespace and slug |
| PUT | /api/v1/prompts/:ns/:slug | Update prompt (creates a new version) |
| DELETE | /api/v1/prompts/:ns/:slug | Delete prompt and all its versions |
| GET | /api/v1/prompts/:ns/:slug/versions | List all versions of a prompt |
| GET | /api/v1/prompts/:ns/:slug/versions/:version | Get a specific prompt version |
| POST | /api/v1/prompts/:ns/:slug/render | Render template with provided variables |
Evals API
Define evaluation criteria, trigger runs against datasets, and retrieve scored results. Runs are async. Poll or use webhooks for completion.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/evals | Create eval definition |
| GET | /api/v1/evals | List eval definitions |
| GET | /api/v1/evals/:id | Get eval definition by ID |
| PUT | /api/v1/evals/:id | Update eval definition |
| DELETE | /api/v1/evals/:id | Delete eval definition |
| POST | /api/v1/evals/:id/run | Trigger a manual eval run |
| GET | /api/v1/evals/runs | List all eval runs (across definitions) |
| GET | /api/v1/evals/runs/:runId | Get run status and metadata |
| GET | /api/v1/evals/:id/results | List scored results for an eval |
| GET | /api/v1/evals/runs/:runId/results | Get results for a specific run |
Datasets API
Versioned collections of test cases used by evals and the playground. Import from JSON/CSV, sample subsets, and link datasets to eval runs.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/datasets | Create a new dataset |
| GET | /api/v1/datasets | List datasets (paginated) |
| GET | /api/v1/datasets/:id | Get dataset by ID |
| PUT | /api/v1/datasets/:id | Update dataset metadata |
| DELETE | /api/v1/datasets/:id | Delete dataset and all versions |
| GET | /api/v1/datasets/:id/versions | List dataset versions |
| POST | /api/v1/datasets/:id/versions | Create a new version (snapshot) |
| GET | /api/v1/datasets/:id/cases | List test cases in current version |
| POST | /api/v1/datasets/:id/cases | Add test cases to dataset |
| PUT | /api/v1/datasets/:id/cases/:caseId | Update a specific test case |
| DELETE | /api/v1/datasets/:id/cases/:caseId | Remove a test case |
| POST | /api/v1/datasets/:id/import | Bulk import cases from JSON or CSV |
| POST | /api/v1/datasets/:id/sample | Random-sample a subset of cases |
| POST | /api/v1/datasets/:id/eval | Run an eval against this dataset |
Playground API
Power the interactive playground. Run completions, compare multiple models side-by-side, browse history, and save iterations as prompt versions.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/playground/run | Execute a single completion request |
| POST | /api/v1/playground/compare | Run the same prompt against multiple models in parallel |
| GET | /api/v1/playground/history | List recent playground runs for the current user |
| GET | /api/v1/playground/history/:id | Get details of a specific playground run |
| POST | /api/v1/playground/save-version | Save current playground state as a new prompt version |
| GET | /api/v1/playground/providers | List available providers and models for the playground |
Sessions & Users API
Inspect proxy session logs, view request timelines, and get per-user usage summaries. Useful for debugging and audit trails.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/sessions | List proxy sessions (paginated, filterable by user/provider/time) |
| GET | /api/v1/sessions/:id | Get session detail including request/response metadata |
| GET | /api/v1/sessions/:id/timeline | Get ordered timeline of events within a session |
| GET | /api/v1/users/:userId/summary | Per-user usage summary (requests, tokens, cost, top models) |
Usage & Cost API
Analytics endpoints for token consumption, cost attribution, and time-series data. Filter by provider, model, key, or time range.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/usage/summary | Aggregate usage summary (total requests, tokens, cost) |
| GET | /api/v1/usage/timeseries | Time-bucketed usage data (hourly, daily, weekly) |
| GET | /api/v1/usage/breakdown | Cost breakdown by provider, model, key, or team |
| GET | /api/v1/usage/prices | Current per-model pricing table used for cost calculation |
Organizations API
Manage organizations, teams within orgs, and application registrations. Entitlements flow: key → org → plan → features.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/orgs | Create a new organization |
| GET | /api/v1/orgs | List organizations for the authenticated user |
| GET | /api/v1/orgs/:orgId | Get organization details and current plan |
| PUT | /api/v1/orgs/:orgId | Update organization settings |
| DELETE | /api/v1/orgs/:orgId | Delete organization (requires owner role) |
| GET | /api/v1/orgs/:orgId/teams | List teams in the organization |
| POST | /api/v1/orgs/:orgId/teams | Create a new team |
| PUT | /api/v1/orgs/:orgId/teams/:teamId | Update team membership or settings |
| DELETE | /api/v1/orgs/:orgId/teams/:teamId | Delete a team |
| GET | /api/v1/orgs/:orgId/apps | List registered applications |
| POST | /api/v1/orgs/:orgId/apps | Register a new application |
| PUT | /api/v1/orgs/:orgId/apps/:appId | Update application configuration |
| DELETE | /api/v1/orgs/:orgId/apps/:appId | Unregister an application |
Auth & Keys API
User authentication (signup, login, sessions) and API key lifecycle management including creation, listing, rotation, and revocation.
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/auth/signup | Create a new user account |
| POST | /api/v1/auth/login | Authenticate and receive a session token |
| POST | /api/v1/auth/logout | Invalidate the current session |
| GET | /api/v1/auth/me | Get current authenticated user profile |
| POST | /api/v1/keys | Create a new API key (scoped to org) |
| GET | /api/v1/keys | List API keys for the current org |
| GET | /api/v1/keys/:keyId | Get key metadata (never returns the secret) |
| PUT | /api/v1/keys/:keyId | Update key name or permissions |
| DELETE | /api/v1/keys/:keyId | Revoke an API key immediately |
| POST | /api/v1/keys/:keyId/rotate | Rotate key. Issues a new secret, old key remains valid for a grace period |
System API
Operational endpoints for health checks, metrics export, and recent gateway log retrieval. No authentication required for /healthz.
| Method | Path | Description |
|---|---|---|
| GET | /healthz | Health check. Returns 200 OK when the gateway is ready |
| GET | /api/v1/metrics | JSON metrics snapshot (request counts, latency percentiles, error rates) |
| GET | /api/v1/logs | Recent gateway logs (filterable by level, provider, time range) |
Authentication
Every request (except /healthz and /api/v1/auth/*) must include one of the following:
| Header | Value | Use Case |
|---|---|---|
X-Ingate-Key | ing_... | API key authentication for programmatic access from your backend or SDK |
Authorization | Bearer <token> | Session token, used by the dashboard and playground web UI |
Key Security
POST /api/v1/keys/:keyId/rotate if a key is compromised.Error Codes
All endpoints return consistent JSON error bodies with a machine-readable code field and a human-readable message.
| HTTP Status | Code | Description |
|---|---|---|
400 | bad_request | Invalid request body or query parameters |
401 | unauthorized | Missing or invalid authentication |
403 | forbidden | Valid auth but insufficient permissions or plan |
404 | not_found | Resource does not exist |
409 | conflict | Resource already exists or version conflict |
422 | validation_error | Semantic validation failure (e.g. invalid template syntax) |
429 | rate_limited | Too many requests. Check Retry-After header |
502 | provider_error | Upstream provider returned an error |
504 | provider_timeout | Upstream provider did not respond in time |
Rate Limits
Rate limits are applied per API key and vary by plan. Current limits are returned in response headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per window |
X-RateLimit-Remaining | Requests remaining in current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only present on 429 responses) |