Skip to content
Omnimatch DocsOpen app

API reference

On this pageConnection & authenticationExample: ask an agentAgentsSearchMemoriesFavouritesThreads & messagesLong-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://agents.example.com. Replace it with your installation’s HTTPS address when connecting from another device. Your product key is for licensing, not API authentication. 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

For an AI assistant, follow the MCP connection guide.

Make your first request

curl https://agents.example.com/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

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

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://agents.example.com/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://agents.example.com/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 an agent’s connected sources directly.

Run a search via the agent's datasource

POST/api/agents/{agentId}/search

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

JSON body (required)

FieldTypeDescription
queryRequiredstring
numResultsOptionalinteger
sourceIdOptionalstringSearch one of the agent's sources by id; omit for the agent's default.
fromYearOptionalintegerOnly results published in this year or later.
toYearOptionalintegerOnly 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

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

Responses

  • 200 OK

Add a memory

POST/api/agents/{agentId}/memories

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

JSON body (required)

FieldTypeDescription
textRequiredstring

Responses

  • 200 OK

Favourites

Keep result cards and retrieve them later.

List or search favourites

GET/api/agents/{agentId}/favourites

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.
qOptionalstring · queryOptional keywords to search favourites.

Responses

  • 200 OK

Add a favourite

POST/api/agents/{agentId}/favourites

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

JSON body (required)

FieldTypeDescription
cardRequiredobject
threadIdOptionalstring

Responses

  • 200 OK

Remove a favourite

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

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.
cardIdRequiredstring · 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

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

Responses

  • 200 OK

Start a new chat thread

POST/api/agents/{agentId}/threads

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.

JSON body

FieldTypeDescription
titleOptionalstring

Responses

  • 200 OK

Read a thread's messages

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

Parameters & responses

Parameters

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.
threadIdRequiredstring · 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

FieldTypeDescription
agentIdRequiredstring · pathAgent id, as returned by GET /api/agents.
threadIdRequiredstring · path

JSON body (required)

FieldTypeDescription
textRequiredstringMaximum 8000 characters.

Responses

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

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://agents.example.com/api/agents/AGENT_ID/threads/THREAD_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

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