Skip to main content

​
Client API Quickstart

OMNI Client API v1 is currently in internal beta. Access is allowlisted and not open to public traffic. If you prefer an SDK-first flow for hosted MCP, see:
  • /getting-started/client-api-sdk-quickstart

​
1. Create an API key

Recommended: use the OMNI app UI (Settings -> API). The control-plane endpoint below is what the UI uses during internal beta. Use an authenticated OMNI session token (your normal app auth) and create a key: 
curl -X POST https://omni-mcp.fly.dev/api/client/keys \
  -H "Authorization: Bearer <omni_user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal-beta-main",
    "mode": "live",
    "scopes": ["fred.read", "mcp.tools.read", "mcp.invoke"]
  }'
Response includes the key once: 
{
  "data": {
    "id": "key_xxx",
    "apiKey": "omni_live_...",
    "mode": "live"
  }
}

​
2. Call Client API v1

curl "https://api.omnibrief.app/v1/fred/search?q=unemployment&limit=5" \
  -H "Authorization: Bearer omni_live_..." \
  -H "X-Request-Id: req_demo_001" \
  -H "Omni-Version: 2026-02-18"

​
Node.js (TypeScript) example

const url = new URL("https://api.omnibrief.app/v1/fred/search");
url.searchParams.set("q", "unemployment");
url.searchParams.set("limit", "5");

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.OMNI_API_KEY}`,
    "X-Request-Id": "req_demo_001",
    "Omni-Version": "2026-02-18",
  },
});

if (!res.ok) {
  const err = await res.json().catch(() => ({}));
  throw new Error(`omni error: ${res.status} ${JSON.stringify(err)}`);
}

const body = await res.json();
console.log(body);

​
Python example

import os
import requests

res = requests.get(
    "https://api.omnibrief.app/v1/fred/search",
    params={"q": "unemployment", "limit": 5},
    headers={
        "Authorization": f"Bearer {os.environ['OMNI_API_KEY']}",
        "X-Request-Id": "req_demo_001",
        "Omni-Version": "2026-02-18",
    },
    timeout=20,
)

if res.status_code >= 400:
    raise RuntimeError(f"omni error: {res.status_code} {res.text}")

print(res.json())

​
Go example

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "os"
  "time"
)

func main() {
  u, _ := url.Parse("https://api.omnibrief.app/v1/fred/search")
  q := u.Query()
  q.Set("q", "unemployment")
  q.Set("limit", "5")
  u.RawQuery = q.Encode()

  req, _ := http.NewRequest("GET", u.String(), nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("OMNI_API_KEY"))
  req.Header.Set("X-Request-Id", "req_demo_001")
  req.Header.Set("Omni-Version", "2026-02-18")

  client := &http.Client{Timeout: 20 * time.Second}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  if resp.StatusCode >= 400 {
    panic(fmt.Sprintf("omni error: %d %s", resp.StatusCode, string(b)))
  }
  fmt.Println(string(b))
}

​
3. MCP tool catalog

curl "https://api.omnibrief.app/v1/mcp/tools" \
  -H "Authorization: Bearer omni_live_..."

​
4. Idempotent POST tool invoke

curl -X POST "https://api.omnibrief.app/v1/mcp/invoke" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Idempotency-Key: idem_001" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "fred.search",
    "arguments": { "q": "cpi", "limit": 3 }
  }'

​
5. Hosted MCP protocol (/mcp)

​
Initialize + list + call

# 1) initialize
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": { "protocolVersion": "2025-11-05" }
  }'

# 2) notifications/initialized (JSON-RPC notification, no id)
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

# 3) tools/list
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

# 4) tools/call (Idempotency-Key required)
curl -X POST "https://api.omnibrief.app/mcp" \
  -H "Authorization: Bearer omni_live_..." \
  -H "Idempotency-Key: idem_mcp_call_001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "fred.search",
      "arguments": { "q": "cpi", "limit": 3 }
    }
  }'

​
6. OpenAPI schema

curl "https://api.omnibrief.app/v1/openapi.json" \
  -H "Authorization: Bearer omni_live_..."

​
Internal beta notes

  • Some accounts may not have Client API access yet.
  • Usage is metered for successful calls.
  • During beta, new endpoints and tools may ship quickly; use the changelog and optional Omni-Version pinning for stability.