Skip to main content

​
Client API Endpoints (Deep Guide)

This page is the operational companion to generated schema docs. Use with:
  • Client API (Generated) for schema field detail
  • /sources/client-api-reference for compact endpoint catalog
  • /sources/client-api-errors for machine-code handling

​
Global integration contract

​
Required auth

Authorization: Bearer omni_live_...

Omni-Version: 2026-02-18
X-Request-Id: req_...

​
Write-safety

Idempotency-Key is required for:
  • POST /v1/mcp/invoke
  • POST /mcp with method=tools/call

​
Billing

  • success (2xx/3xx) billable
  • failed calls (4xx/5xx) non-billable
  • replayed idempotent responses non-billable

​
GET /v1/health

Purpose:
  • key/auth sanity check
  • request-id plumbing verification
Success example: 
{
  "object": "health",
  "status": "ok",
  "request_id": "req_...",
  "mode": "live"
}
High-signal failures:
  • missing_api_key
  • invalid_api_key
  • auth_rejected

​
GET /v1/openapi.json

Purpose:
  • canonical contract source for SDK generation and CI drift checks
Production pattern:
  1. fetch schema with pinned Omni-Version
  2. diff against approved baseline
  3. block promotion on breaking diff

​
GET /v1/fred/search

Request: 
GET /v1/fred/search?q=inflation&limit=5
Parameters:
  • q required string
  • limit optional integer 1-50 (default 10)
Success shape: 
{
  "object": "fred.search_result",
  "data": {
    "count": 5,
    "items": []
  }
}
Common failures:
  • missing_q
  • invalid_parameter
  • fred_invalid_request
  • fred_upstream_error

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

Request: 
GET /v1/fred/series/CPIAUCSL?observation_start=2024-01-01&limit=24
Parameters:
  • series_id required path value
  • observation_start/observation_end optional YYYY-MM-DD
  • limit optional integer 1-1000
Success shape: 
{
  "object": "fred.series_result",
  "data": {
    "series_id": "CPIAUCSL",
    "observations": []
  }
}
Common failures:
  • missing_series_id
  • invalid_parameter
  • fred_invalid_request
  • fred_upstream_error

​
Legacy MCP compatibility routes

​
GET /v1/mcp/tools

Purpose:
  • legacy compatibility for non-JSON-RPC clients
Required scope:
  • mcp.tools.read
Returns deprecation headers:
  • Deprecation: true
  • Sunset: 2026-08-31T00:00:00Z
  • Link: </sources/client-api-mcp-hosted>; rel="successor-version"

​
POST /v1/mcp/invoke

Purpose:
  • legacy compatibility invocation route
Required headers: 
Authorization: Bearer omni_live_...
Idempotency-Key: idem_...
Content-Type: application/json
Request body: 
{
  "tool": "fred.search",
  "arguments": { "q": "inflation", "limit": 3 }
}
High-signal failures:
  • missing_idempotency_key
  • invalid_json
  • invalid_payload
  • unknown_tool
  • idempotency_conflict
  • mcp_invocation_failed

​
Hosted MCP transport

​
POST /mcp (canonical)

Supported methods:
  • initialize
  • notifications/initialized
  • ping
  • tools/list
  • tools/call
Method-level requirements:
MethodRequired scopesBillable
initializeauth onlyNo
notifications/initializedauth onlyNo
pingauth onlyNo
tools/listmcp.tools.readYes (1 unit on success)
tools/callmcp.invoke + tool scopesYes (1 unit on first success)
Canonical sequence:
  1. initialize
  2. notifications/initialized
  3. tools/list
  4. tools/call
tools/call example: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "fred.search",
    "arguments": { "q": "inflation", "limit": 2 }
  }
}
Required header for tools/call: 
Idempotency-Key: idem_...
Replay behavior:
  • replayed response includes Idempotency-Replayed: true
  • replay remains non-billable

​
GET /mcp

Purpose:
  • streamable transport metadata (text/event-stream)
Billing:
  • zero-unit transport call

​
DELETE /mcp

Purpose:
  • explicit session close
Expected response:
  • 204 No Content
Billing:
  • zero-unit transport call

​
GET /sse

Purpose:
  • SSE compatibility bootstrap for older MCP clients
Recommendation:
  • use /mcp for net-new integrations
Billing:
  • zero-unit transport call

​
Endpoint readiness checklist

  • key scopes validated per endpoint/method
  • request-id propagation verified
  • idempotency enforced for write-like calls
  • retry policy aligned to /sources/client-api-retries
  • alerting keyed on machine fields, not message text
  • billing behavior validated for success/failure/replay
  • /sources/client-api-reference
  • /sources/client-api-errors
  • /sources/client-api-migrations
  • /sources/client-api-openapi