Developer API reference

On this page

Connection & authentication Machine-readable documentation Example: ask an agent Agents Search Memories Favourites Threads & messages MCP tools Long-running replies

Use the REST API to search your sources, save context and talk to your agents from another application.

Connection & authentication

The base URL for these examples is https://omnimatch.ai. For private installations, use your own address and follow the on-premise API guide. Available operations follow your account’s permissions and enabled capabilities.

Bearer token

Send your API key or OAuth token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get a token

OAuth: add https://omnimatch.ai/mcp to an MCP client with Streamable HTTP and complete the browser sign-in. The REST API accepts the same token. Read the authentication guide.
Connect code: copy a single-use code from Connect via MCP, then exchange it within 15 minutes using POST /api/connect/exchange with { "code": "omc_...", "client": "your-client-name" }. The response supplies token and mcpUrl. The token is scoped to agent work and cannot manage API keys, billing or account settings. Connected clients are revocable in Settings.
API key: create a long-lived key in Settings → API keys and send it as the bearer token.

For an AI assistant, follow the MCP connection guide.

Make your first request

curl https://omnimatch.ai/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Requests with a JSON body also need Content-Type: application/json.

Machine-readable documentation

Download the OpenAPI 3.1 specification for paths, request fields and response schemas. Agents can also retrieve this page as ordinary HTML; every endpoint below is included in the server response, including collapsed details.

The documentation index and authentication instructions provide additional entry points for assistants.

Example: ask an agent

First list agents with GET /api/agents. Replace AGENT_ID below with an id from that response, then create a thread:

curl -X POST https://omnimatch.ai/api/agents/AGENT_ID/threads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

Use the returned thread.id in place of THREAD_ID:

curl -X POST https://omnimatch.ai/api/agents/AGENT_ID/threads/THREAD_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Summarise our leave policy."}'

Agents

List the agents available to your account. Use the returned agent id in subsequent requests.

List available agents

GET/api/agents

Parameters & responses

Responses

200 OK

Search

Search an agent’s connected sources directly.

Run a search via the agent's datasource

POST/api/agents/{agentId}/search

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

JSON body (required)

Field	Type	Description
`query`Required	string
`numResults`Optional	integer
`sourceId`Optional	string	Search one of the agent's sources by id; omit for the agent's default.
`fromYear`Optional	integer	Only results published in this year or later.
`toYear`Optional	integer	Only results published in this year or earlier.

Responses

200 Search results
402 No subscription

Memories

Read or save context that your agent can use in future conversations.

List remembered facts

GET/api/agents/{agentId}/memories

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

Responses

200 OK

Add a memory

POST/api/agents/{agentId}/memories

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

JSON body (required)

Field	Type	Description
`text`Required	string

Responses

200 OK

Favourites

Keep result cards and retrieve them later.

List or search favourites

GET/api/agents/{agentId}/favourites

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.
`q`Optional	string · query	Optional keywords to search favourites.

Responses

200 OK

Add a favourite

POST/api/agents/{agentId}/favourites

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

JSON body (required)

Field	Type	Description
`card`Required	object
`threadId`Optional	string

Responses

200 OK

Remove a favourite

DELETE/api/agents/{agentId}/favourites/{cardId}

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.
`cardId`Required	string · path

Responses

200 OK

Threads & messages

Create a conversation, send a message and read the agent’s reply.

List chat threads

GET/api/agents/{agentId}/threads

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

Responses

200 OK

Start a new chat thread

POST/api/agents/{agentId}/threads

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.

JSON body

Field	Type	Description
`title`Optional	string

Responses

200 OK

Read a thread's messages

GET/api/agents/{agentId}/threads/{threadId}/messages

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.
`threadId`Required	string · path

Responses

200 OK

Send a message and run a turn

POST/api/agents/{agentId}/threads/{threadId}/messages

Answers inline when the agent finishes quickly. A research turn usually takes longer than one HTTP request should wait, so 202 is the normal reply, not an error: the turn keeps running and the answer appears at GET on this same path.

Parameters & responses

Parameters

Field	Type	Description
`agentId`Required	string · path	Agent id, as returned by GET /api/agents.
`threadId`Required	string · path

JSON body (required)

Field	Type	Description
`text`Required	string	Maximum 8000 characters.

Responses

200 The agent replied within the wait.
202 Still working. Poll GET on this path for the reply.

MCP tools

Connect to https://omnimatch.ai/mcp using Streamable HTTP. OAuth clients can sign in through the browser; other clients send their bearer token. Follow the client setup instructions or the MCP user guide.

Use MCP tools/list to discover the tools available to the connected account. They cover agent discovery, search, memories, favourites and conversations, with additional capabilities depending on access. The server’s tool definitions provide the current names and input schemas.

Long-running replies

A message can return 202 with { "status": "working" } while the agent continues. Poll the messages endpoint with GET to read the reply. Do not resend the message just because the turn is still running.

curl https://omnimatch.ai/api/agents/AGENT_ID/threads/THREAD_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

A completed inline reply returns 200 with { "status": "complete", "text": "…" }.