Skip to main content

​
Client API Reference

This is the operational, endpoint-by-endpoint reference for OMNI Client API. For schema-level request/response definitions (and interactive “try it” functionality), use:
  • Client API (Generated) in the left navigation
  • /sources/client-api-openapi

​
Base URL

Production: 
https://api.omnibrief.app

​
Authentication and global headers

All endpoints require an OMNI API key: 
Authorization: Bearer omni_live_...
HeaderRequiredUsed for
Authorization: Bearer ...YesAuth to Client API and hosted MCP transport.
Omni-Version: YYYY-MM-DDNoBehavior pinning during beta. Recommended for production integrations.
X-Request-Id: req_...NoEnd-to-end trace correlation (echoed back and included in errors).
Idempotency-Key: idem_...ConditionalRequired for POST /v1/mcp/invoke and hosted MCP tools/call over POST /mcp.
Content-Type: application/jsonConditionalRequired when sending JSON bodies.

​
Endpoint contract matrix

EndpointMethodRequired scopesBillable unitsIdempotency-KeyStatusCommon error codes
/v1/openapi.jsonGETauth only1 on successNoStablemissing_api_key, invalid_api_key, auth_rejected, rate_limit_exceeded, service_disabled
/v1/healthGETauth only1 on successNoStablemissing_api_key, invalid_api_key, auth_rejected, rate_limit_exceeded, service_disabled
/v1/fred/searchGETfred.read1 on successNoStablemissing_q, invalid_parameter, insufficient_scope, auth/rate-limit codes
/v1/fred/series/{series_id}GETfred.read1 on successNoStablemissing_series_id, invalid_parameter, insufficient_scope, auth/rate-limit codes
/v1/mcp/toolsGETmcp.tools.read1 on successNoDeprecated compatibility routeinsufficient_scope, auth/rate-limit codes
/v1/mcp/invokePOSTmcp.invoke + tool scope1 on first successYesDeprecated compatibility routemissing_idempotency_key, invalid_json, invalid_payload, unknown_tool, idempotency_conflict, mcp_invocation_failed
/mcpPOSTmethod-dependent1 for tools/list/tools/call successRequired for tools/callCanonical hosted MCP routeJSON-RPC errors -32700, -32600, -32601, -32602, -32001, -32002, -32603
/mcpGETauth only0NoHosted stream transportauth/rate-limit codes
/mcpDELETEauth only0NoSession closeauth/rate-limit codes
/sseGETauth only0NoCompatibility transportauth/rate-limit codes

​
Endpoint-by-endpoint playbooks

​
GET /v1/openapi.json

Purpose:
  • Canonical source of contract truth for generated references, SDK generation, and CI contract diffing.
Operational notes:
  • Treat OpenAPI diffs as release-gating input.
  • Pin Omni-Version when validating contract upgrades.

​
GET /v1/health

Purpose:
  • Fast auth sanity check and request-id plumbing validation.
Expected success shape: 
{
  "object": "health",
  "status": "ok",
  "request_id": "req_...",
  "mode": "live"
}

​
GET /v1/fred/search

Query parameters:
  • q required string
  • limit optional integer (1-50, default 10)
Recommended production posture:
  • normalize + cache by (q, limit)
  • fail fast on invalid local inputs to reduce avoidable 400s

​
GET /v1/fred/series/{series_id}

Path/query parameters:
  • series_id required path string
  • optional observation_start, observation_end (YYYY-MM-DD)
  • limit optional integer (default 1000)
Recommended production posture:
  • cache by (series_id, observation_start, observation_end, limit)
  • handle sparse/empty datasets without assuming row presence

​
GET /v1/mcp/tools (legacy compatibility)

Migration target:
  • replace with hosted MCP tools/list over POST /mcp
Deprecation headers are returned on this route.

​
POST /v1/mcp/invoke (legacy compatibility)

Required headers: 
Authorization: Bearer omni_live_...
Idempotency-Key: idem_...
Content-Type: application/json
Request body shape: 
{
  "tool": "fred.search",
  "arguments": { "q": "cpi", "limit": 3 }
}
Migration target:
  • replace with hosted MCP tools/call over POST /mcp

​
Hosted MCP (/mcp, /sse)

Hosted MCP is the canonical MCP integration surface. Method-level scope rules for POST /mcp:
JSON-RPC methodRequired scopes
initializeauth only
notifications/initializedauth only
pingauth only
tools/listmcp.tools.read
tools/callmcp.invoke + tool scope(s)
tools/call safety rules:
  • Idempotency-Key is required.
  • On replay, OMNI returns Idempotency-Replayed: true.
  • Replays do not double bill.

​
POST /mcp initialize sequence

  1. send initialize
  2. send notifications/initialized (notification; no id)
  3. then call tools/list and tools/call

​
GET /mcp

Returns stream transport metadata (text/event-stream).

​
DELETE /mcp

Best-effort session close (204 on success).

​
GET /sse

SSE compatibility bootstrap route. Prefer /mcp for net-new integrations.

​
Global billing semantics

  • only successful calls (2xx/3xx) are billable
  • failed calls (4xx/5xx) are non-billable
  • idempotency replays are non-billable
  • transport-only MCP calls (GET /mcp, DELETE /mcp, GET /sse) are zero-unit

​
Global integration checklist

  • pin Omni-Version in production
  • send/log X-Request-Id on every call
  • enforce scoped keys and least privilege
  • use idempotency for write-like methods
  • implement retry policy from /sources/client-api-retries
  • branch on machine fields only (error.type, error.code, JSON-RPC codes)
  • /sources/client-api-endpoints
  • /sources/client-api-openapi
  • /sources/client-api-errors
  • /sources/client-api-migrations
  • /sources/client-api-retries