> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.polytomic.com/2025-09-18/api-reference/operations/search/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server.

# Search Operations

POST https://app.polytomic.com/api/operations/search
Content-Type: application/json

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.

Reference: https://apidocs.polytomic.com/api-reference/operations/search

## Authentication

- `Authorization` header (bearer token, required) — Bearer user API key
- `Authorization` header (basic auth, required) — Basic organization-scoped API key

## Request

### Body (application/json)

This endpoint expects a SearchOperationsRequest.

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

## Response

### 200

OK

- `data` (SearchOperationsResponse, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `key` (string, optional)
- `message` (string, optional)
- `metadata` (map from string to any, optional)
- `status` (integer, optional)

### 429 Too Many Requests Error

Too Many Requests

- `key` (string, optional)
- `message` (string, optional)
- `metadata` (map from string to any, optional)
- `status` (integer, optional)

### 502 Bad Gateway Error

Bad Gateway

- `key` (string, optional)
- `message` (string, optional)
- `metadata` (map from string to any, optional)
- `status` (integer, optional)

### 503 Service Unavailable Error

Service Unavailable

- `key` (string, optional)
- `message` (string, optional)
- `metadata` (map from string to any, optional)
- `status` (integer, optional)

## Types

### SearchOperationsResponse

- `results` (list of OperationSearchResult, optional, nullable) — Ranked results in the same order as the input queries.
- `sourceSha256` (string, optional) — SHA-256 digest of the OpenAPI-derived operation catalog source.

### OperationSearchResult

- `matches` (list of OperationMatch, optional, nullable) — Operations ranked by probability of being the single best choice for this task; empty when no match wins.
- `noMatchProbability` (double, optional) — Relative probability that none of the documented operations is the best choice.
- `query` (string, optional) — The trimmed input task.

### OperationMatch

- `authAudience` (string, optional) — Authentication audience declared by the operation; a match does not grant access.
- `id` (string, optional) — Stable METHOD and path identifier.
- `method` (string, optional) — HTTP method of the operation.
- `openapiPointer` (string, optional) — JSON pointer into the public OpenAPI paths object.
- `path` (string, optional) — Templated public API path.
- `selectionProbability` (double, optional) — Relative probability of selection as the single best operation for this query, not an independent relevance score.
- `summary` (string, optional) — Short description of the operation.

## Examples

**Request**

```json
{
  "queries": [
    "string"
  ]
}
```

**Response**

```json
{
  "data": {
    "results": [
      {
        "matches": [
          {
            "authAudience": "string",
            "id": "string",
            "method": "string",
            "openapiPointer": "string",
            "path": "string",
            "selectionProbability": 1.1,
            "summary": "string"
          }
        ],
        "noMatchProbability": 1.1,
        "query": "string"
      }
    ],
    "sourceSha256": "string"
  }
}
```

**SDK Code**

```python
import requests

url = "https://app.polytomic.com/api/operations/search"

payload = { "queries": ["string"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.polytomic.com/api/operations/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"queries":["string"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.polytomic.com/api/operations/search"

	payload := strings.NewReader("{\n  \"queries\": [\n    \"string\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.polytomic.com/api/operations/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"queries\": [\n    \"string\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://app.polytomic.com/api/operations/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"queries\": [\n    \"string\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://app.polytomic.com/api/operations/search', [
  'body' => '{
  "queries": [
    "string"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.polytomic.com/api/operations/search");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"queries\": [\n    \"string\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["queries": ["string"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://app.polytomic.com/api/operations/search")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```