Omnimatch Agents: API & MCP

Programmatic access to your agents' capabilities: run searches, remember context, save the results you like, and browse chat history. Authenticate over OAuth, a one-time connect code, or an API key (see Authentication below).

Getting the most out of it

Let it remember. Save what you're looking for (must-haves, deal-breakers, companies to target) as memories, so every future search is sharper and you don't repeat yourself.
Save the good ones. Keep results you like as favourites; they show up on your Saved page and can be searched later.
A favourite keeps what you saw. Each one stores the card as it stood when you kept it, so it stays readable long after the source has moved on.
For ongoing use, connect the MCP (below) inside your assistant so it's always on hand and keeps context between chats. For a quick one-off, the REST API is the simplest option.

Authentication

Every call carries a bearer token:

Authorization: Bearer oma_live_xxxxxxxxxxxxxxxx

There are three ways to get one, best first:

OAuth 2.0 (for MCP clients). Clients that speak MCP OAuth (Claude Connectors, Claude Code, Codex, Cursor, VS Code) need only the server URL and run a browser sign-in. See https://omnimatch.ai/auth.md. The REST API takes the same token.
Connect code (for other harnesses). Copy a one-time code (prefix omc_, valid 15 minutes, single use) from the web app, then exchange it: POST https://omnimatch.ai/api/connect/exchange with body { "code": "omc_...", "client": "<short tool name>" }. The response is { "token": "oma_...", "mcpUrl": "..." }. The token is scoped to working with your agents and can't touch API keys, billing or account settings. Each connected client is revocable in Settings.
Manual API key. Create a long-lived key in the app (Settings → API keys) and send it as the bearer token above.

Base URL

https://omnimatch.ai

REST endpoints

Method	Path	Description
GET	/api/agents	List available agents
POST	/api/agents/{agentId}/search	Run a search. Body: `{ "query": "..." }`, optionally `numResults`, `sourceId`, `fromYear`, `toYear`
GET	/api/agents/{agentId}/memories	List remembered facts
POST	/api/agents/{agentId}/memories	Add a memory. Body: `{ "text": "..." }`
GET	/api/agents/{agentId}/favourites	List or search favourites. Add `?q=keywords` to search
POST	/api/agents/{agentId}/favourites	Save a favourite. Body: `{ "card": { ... } }`
DELETE	/api/agents/{agentId}/favourites/{cardId}	Remove a favourite
GET	/api/agents/{agentId}/threads	List chat threads
POST	/api/agents/{agentId}/threads	Start a thread. Body: `{ "title": "..." }` (optional)
GET	/api/agents/{agentId}/threads/{threadId}/messages	Read thread messages
POST	/api/agents/{agentId}/threads/{threadId}/messages	Send a message. Body: `{ "text": "..." }`

Example: ask an agent a question

Start a thread, then send it a message:

curl -X POST https://omnimatch.ai/api/agents/my-agent/threads \
  -H "Authorization: Bearer $OMA_API_KEY" -H "Content-Type: application/json" -d '{}'
# → {"thread":{"id":"thr_...", ...}}

curl -X POST https://omnimatch.ai/api/agents/my-agent/threads/thr_.../messages \
  -H "Authorization: Bearer $OMA_API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"What ventilation rate applies to an internal bathroom?"}'

A quick answer comes straight back as 200 {"status":"complete","text":"..."}. An agent that has to go and research will usually take longer than a single request should be held open, so you get 202 {"status":"working"} instead — that is the normal case, not a failure. The turn carries on, and the reply appears at GET on the same path. Poll it every few seconds.

Full machine-readable spec: /openapi.json

Example: run a recruitment search

curl -X POST https://omnimatch.ai/api/agents/recruitment/search \
  -H "Authorization: Bearer $OMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"senior backend engineers in Berlin with Go experience"}'

MCPModel Context Protocol

Connect any MCP client to the same capabilities at:

https://omnimatch.ai/mcp

Use HTTP (Streamable) transport. Clients that support MCP OAuth just add the URL and sign in through the browser; others send header Authorization: Bearer oma_… (see Authentication above). Setup for specific tools: https://omnimatch.ai/connect. Tools: execute_search, act_as_agent (serve a hired agent's side of the chat with your own model) with record_agent_turn (commit each exchange to the agent's chat history), list_agents, hire_agent, list_memories, add_memory, delete_memory, list_favourites (search your favourites), add_favourite, remove_favourite, list_threads, get_thread_messages, plus routine (scheduled search) tools. MCP clients that support Cloudflare Code Mode can wrap these into a TypeScript API automatically.