Service Gateway API
Complete REST API reference for the NaaP Service Gateway — public endpoints, admin management, and agent/MCP integration.
Overview#
The Service Gateway API is organized into three groups:
- Public Routes — Discovery, catalog, pricing, rankings, health (some require auth)
- Proxy Route — The core engine route that forwards consumer requests to upstreams
- Admin Routes — Connector CRUD, endpoint management, secrets, keys, plans, usage, templates
All routes are under /api/v1/gw/. Admin routes require a valid JWT session and respond based on the caller's team scope (via the x-team-id header).
Public Routes#
Discovery#
GET /api/v1/gw/discoveryReturns the gateway discovery document with available endpoints, supported formats, and auth methods. No authentication required.
Response:
| 1 | { |
| 2 | "name": "NaaP Service Gateway", |
| 3 | "version": "1.0.0", |
| 4 | "endpoints": { |
| 5 | "catalog": "/api/v1/gw/catalog", |
| 6 | "pricing": "/api/v1/gw/pricing", |
| 7 | "rankings": "/api/v1/gw/rankings", |
| 8 | "mcp": "/api/v1/gw/mcp", |
| 9 | "discovery": "/api/v1/gw/discovery", |
| 10 | "proxy": "/api/v1/gw/{connector}/{path}" |
| 11 | }, |
| 12 | "formats": ["native", "openai", "mcp"], |
| 13 | "auth": { |
| 14 | "masterKey": { "prefix": "gwm_", "header": "Authorization", "scheme": "Bearer" }, |
| 15 | "connectorKey": { "prefix": "gw_", "header": "Authorization", "scheme": "Bearer" }, |
| 16 | "jwt": { "header": "Authorization", "scheme": "Bearer" } |
| 17 | } |
| 18 | } |
Catalog#
GET /api/v1/gw/catalogReturns the tool catalog of published connectors. Requires authentication.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | native | Response format: native, openai, or mcp |
category | string | — | Filter by connector category |
page | number | 1 | Page number |
pageSize | number | 50 | Results per page (max 200) |
Formats:
native— Full metadata including pricing, health, metrics, rankings, and gateway infoopenai— OpenAI-compatible function definitions for tool callingmcp— MCP-compatible tools list
Catalog Detail#
GET /api/v1/gw/catalog/{slug}
GET /api/v1/gw/catalog/{slug}/metrics
GET /api/v1/gw/catalog/{slug}/rankingsReturns detailed information, metrics, or capability rankings for a specific connector.
Pricing#
GET /api/v1/gw/pricing
GET /api/v1/gw/pricing/{slug}
GET /api/v1/gw/pricing/{slug}/estimateReturns pricing information for connectors. The estimate endpoint accepts usage parameters and returns projected costs.
Rankings#
GET /api/v1/gw/rankingsReturns capability rankings across all published connectors, useful for agent tool selection.
Health#
GET /api/v1/gw/healthReturns overall gateway health status.
MCP (Model Context Protocol)#
POST /api/v1/gw/mcpJSON-RPC endpoint implementing the MCP protocol. Supports two methods:
tools/list — List available tools:
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}tools/call — Execute a tool (routed through the proxy pipeline):
| 1 | { |
| 2 | "jsonrpc": "2.0", |
| 3 | "method": "tools/call", |
| 4 | "params": { |
| 5 | "name": "openai__chat-completions", |
| 6 | "arguments": { "model": "gpt-4", "messages": [{"role": "user", "content": "Hello"}] } |
| 7 | }, |
| 8 | "id": 2 |
| 9 | } |
Tool names follow the {connector}__{endpoint} convention.
Proxy Route#
GET|POST|PUT|PATCH|DELETE /api/v1/gw/{connector}/{...path}The core engine route. Accepts any HTTP method and routes the request through the full pipeline (Authorize, Resolve, Policy, Validate, Cache, Secrets, Transform, Proxy, Respond, Log).
Auth: JWT (Bearer <token> + x-team-id), API key (Bearer gw_xxx), or master key (Bearer gwm_xxx)
Request Headers:
| Header | Description |
|---|---|
Authorization | Bearer token (JWT, API key, or master key) |
x-team-id | Team context (for JWT auth) |
x-request-id | Optional — correlates logs |
x-trace-id | Optional — distributed tracing |
Idempotency-Key | Optional — prevents duplicate non-GET requests |
Error Response Format:
| 1 | { |
| 2 | "success": false, |
| 3 | "error": { |
| 4 | "code": "RATE_LIMITED", |
| 5 | "message": "Rate limit exceeded" |
| 6 | }, |
| 7 | "requestId": "...", |
| 8 | "traceId": "..." |
| 9 | } |
Special Route: Daydream WHIP#
POST /api/v1/gw/daydream-whipWebRTC WHIP SDP proxy for Daydream video streaming. Bypasses the generic engine for WebRTC-specific handling.
Admin Routes#
All admin routes require a valid JWT session. Team scope is determined by the x-team-id header. Results are filtered to the caller's team (or personal scope if no team header).
Connectors#
| 1 | GET /api/v1/gw/admin/connectors — List connectors |
| 2 | POST /api/v1/gw/admin/connectors — Create draft connector |
| 3 | GET /api/v1/gw/admin/connectors/{id} — Get connector detail |
| 4 | PATCH /api/v1/gw/admin/connectors/{id} — Update connector |
| 5 | DELETE /api/v1/gw/admin/connectors/{id} — Delete connector |
List Query Parameters:
| Parameter | Type | Description |
|---|---|---|
scope | string | own, public, or all (default) |
status | string | Filter by status (draft, published) |
category | string | Filter by category |
page / pageSize | number | Pagination |
Create Body Fields:
| Field | Type | Required | Description |
|---|---|---|---|
slug | string | Yes | URL-safe identifier |
displayName | string | Yes | Human-readable name |
description | string | No | Description |
category | string | No | Category tag |
upstreamBaseUrl | string | Yes | Target API base URL |
allowedHosts | string[] | Yes | SSRF-safe host whitelist |
authType | string | Yes | bearer, basic, header, query, aws-s3, none |
authConfig | object | No | Auth-specific configuration |
secretRefs | string[] | No | Secret names needed by the connector |
defaultTimeout | number | No | Default timeout in ms |
streamingEnabled | boolean | No | Enable SSE passthrough |
responseWrapper | boolean | No | Wrap responses in NaaP envelope |
visibility | string | No | private or public |
agentDescription | string | No | LLM-readable description |
Endpoints#
| 1 | GET /api/v1/gw/admin/connectors/{id}/endpoints — List endpoints |
| 2 | POST /api/v1/gw/admin/connectors/{id}/endpoints — Add endpoint |
| 3 | GET /api/v1/gw/admin/connectors/{id}/endpoints/{endpointId} — Get endpoint |
| 4 | PATCH /api/v1/gw/admin/connectors/{id}/endpoints/{endpointId} — Update endpoint |
| 5 | DELETE /api/v1/gw/admin/connectors/{id}/endpoints/{endpointId} — Delete endpoint |
Secrets#
GET /api/v1/gw/admin/connectors/{id}/secrets — List secret names (values never returned)
POST /api/v1/gw/admin/connectors/{id}/secrets — Store a secret
DELETE /api/v1/gw/admin/connectors/{id}/secrets/{name} — Delete a secretPublish & Test#
POST /api/v1/gw/admin/connectors/{id}/publish — Publish connector (draft → published)
POST /api/v1/gw/admin/connectors/{id}/test — Test upstream connectivityOpenAPI#
GET /api/v1/gw/admin/connectors/{id}/openapi — Generate OpenAPI spec for the connectorPricing & Rankings#
| 1 | GET /api/v1/gw/admin/connectors/{id}/pricing — Get/set connector pricing |
| 2 | PUT /api/v1/gw/admin/connectors/{id}/pricing — Update pricing |
| 3 | GET /api/v1/gw/admin/connectors/{id}/rankings — Get capability rankings |
| 4 | PUT /api/v1/gw/admin/connectors/{id}/rankings — Update rankings |
API Keys#
| 1 | GET /api/v1/gw/admin/keys — List API keys |
| 2 | POST /api/v1/gw/admin/keys — Create API key (returns gw_ key once) |
| 3 | GET /api/v1/gw/admin/keys/{id} — Get key details |
| 4 | DELETE /api/v1/gw/admin/keys/{id} — Revoke key |
| 5 | POST /api/v1/gw/admin/keys/{id}/rotate — Rotate key (returns new gw_ key) |
Master Keys#
| 1 | GET /api/v1/gw/admin/master-keys — List master keys |
| 2 | POST /api/v1/gw/admin/master-keys — Create master key (returns gwm_ key once) |
| 3 | GET /api/v1/gw/admin/master-keys/{id} — Get key details |
| 4 | DELETE /api/v1/gw/admin/master-keys/{id} — Revoke key |
| 5 | POST /api/v1/gw/admin/master-keys/{id}/rotate — Rotate key |
Usage Plans#
| 1 | GET /api/v1/gw/admin/plans — List usage plans |
| 2 | POST /api/v1/gw/admin/plans — Create plan |
| 3 | GET /api/v1/gw/admin/plans/{id} — Get plan |
| 4 | PATCH /api/v1/gw/admin/plans/{id} — Update plan |
| 5 | DELETE /api/v1/gw/admin/plans/{id} — Delete plan |
Usage & Metrics#
| 1 | GET /api/v1/gw/admin/usage/summary — Usage summary for the team |
| 2 | GET /api/v1/gw/admin/usage/by-connector — Usage broken down by connector |
| 3 | GET /api/v1/gw/admin/usage/by-key — Usage broken down by API key |
| 4 | GET /api/v1/gw/admin/usage/timeseries — Usage over time |
| 5 | GET /api/v1/gw/admin/metrics/aggregate — Aggregated performance metrics |
Health Checks#
GET /api/v1/gw/admin/health — List all health check results
GET /api/v1/gw/admin/health/{id} — Health history for a connector
POST /api/v1/gw/admin/health/check — Trigger health checksTemplates#
GET /api/v1/gw/admin/templates — List available connector templatesReturns the 19 pre-built connector templates (OpenAI, Stripe, ClickHouse, etc.) that can be used to quickly create new connector instances.
Next Steps#
- Service Gateway Concept — Architecture and pipeline details
- Service Gateway Setup Guide — Step-by-step connector creation