---
title: "Search Operations"
method: POST
path: "/api/operations/search"
tags: ["Operations"]
---

# Search Operations

`POST /api/operations/search`

## Request

- Base URL: `https://app.polytomic.com`
- URL: `https://app.polytomic.com/api/operations/search`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Finds documented REST operations for up to three plain-language tasks in one request.

This endpoint returns HTTP 503 when operation search is not configured for the
API deployment. Check [search availability](../../../api-reference/operations/get-search-availability)
before offering operation search in a client.

Each question counts against three fixed UTC-window budgets: 12 questions per
Organization per minute, 300 per Organization per day, and 60 per minute
across the deployment. A request with three tasks uses three questions from
each budget. At most eight provider calls run concurrently across the
deployment. These are initial defaults; operators can adjust them with
`API_DISCOVERY_ORG_QUESTIONS_PER_MINUTE`,
`API_DISCOVERY_ORG_QUESTIONS_PER_DAY`,
`API_DISCOVERY_GLOBAL_QUESTIONS_PER_MINUTE`, and
`API_DISCOVERY_GLOBAL_IN_FLIGHT`. All settings must be positive integers.
Daily budgets reset at 00:00 UTC; minute budgets reset on UTC minute
boundaries, which can allow a short burst across adjacent minutes. Calls
rejected by a limit return HTTP 429 with a `Retry-After` header in seconds.
A submitted call still counts if the provider fails. If admission is
unavailable, the endpoint returns HTTP 503 instead of contacting the provider.

Pass `operationIds` to rank only those documented operations. The list must
contain at least one unique, known `METHOD /api/path` ID. If you omit it,
Polytomic ranks all documented operations. Every ranking also includes the
no-match option. The response's `sourceSha256` is the SHA-256 of the internal processed MCP
spec artifact used to build the operation catalog. It is not the digest of the
public OpenAPI document. Treat it as an opaque catalog version for detecting
drift between the API and MCP deployments.

Each task has its own ranking in the same order as `queries`. The scores within
one task describe the relative probability of choosing each operation as the
single best option, including the no-match option. They are not independent
relevance scores and cannot be compared across tasks.

If no documented operation is the best choice, `matches` is empty. Results
come from the public API contract, not your Organization's data. Finding an
operation does not authorize you to call it; the operation's own authentication
and permissions still apply.

## Headers

- `X-Polytomic-Version` string

## Request body

- SearchOperationsRequest
  - `limit` integer: Maximum operations per task, from 1 to 10; defaults to 5
  - `operationIds` string[]: Optional nonempty list of unique stable operation IDs to rank; omitted to rank the full catalog
  - `queries` string[], required: One to three plain-language tasks to find API operations for

## Response `200`

OK

- SearchOperationsEnvelope
  - `data` SearchOperationsResponse
    - `results` OperationSearchResult[], nullable: Ranked results in the same order as the input queries
      - `matches` OperationMatch[], nullable: Operations ranked by probability of being the single best choice for this task; empty when no match wins
        - `authAudience` string: Authentication audience declared by the operation; a match does not grant access.
        - `id` string: Stable METHOD and path identifier
        - `method` string: HTTP method of the operation
        - `openapiPointer` string: JSON pointer into the public OpenAPI paths object
        - `path` string: Templated public API path
        - `selectionProbability` number, double: Relative probability of selection as the single best operation for this query, not an independent relevance score
        - `summary` string: Short description of the operation
      - `noMatchProbability` number, double: Relative probability that none of the documented operations is the best choice
      - `query` string: The trimmed input task
    - `sourceSha256` string: SHA-256 digest of the OpenAPI-derived operation catalog source

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-22** `d80b0fdea14e`: 1 breaking, 2 warning, 1 info
  - the `data` response's property type changed from `object` to no type for status `200`
  - removed the optional property `data/results` from the response with the `200` status
  - removed the optional property `data/sourceSha256` from the response with the `200` status
  - added `#/components/schemas/SearchOperationsResponse` to the `data` response property `allOf` list for the response status `200`
- **2026-09-25** `19a8683c3363`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/operations/search/post.md)

---

[API](https://skmtc.dev/polytomic/apis/polytomic-api.md) - [All operations](https://skmtc.dev/polytomic/apis/polytomic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/polytomic/apis/polytomic-api/revisions/3c88180d2470?raw)