> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.buildwithorbit.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.buildwithorbit.ai/_mcp/server.

# Search Public Endpoints

POST https://api.buildwithorbit.ai/v1/search
Content-Type: application/json

# Search Public Endpoints

Describe your goal in `q`. Search returns matching public endpoints and evaluates what each one does, when to use it, and its limitations so the agent can select the best fit.

## Request

`POST /v1/search`

```json
{ "q": "Get Current Weather" }
```

```json
{ "q": "Add tracking details for an existing paypal order" }
```

`q` is required and capped at 512 characters. No other body field is accepted; unknown fields return `400`.

**Query parameters**

* `limit` — results per page (default 10, max 25)
* `cursor` — pass `meta.nextCursor` from the previous response

Pagination stops at 40 results total; a cursor past 40 is rejected.

## Response

Each result carries `id`, `resourceType`, `name`, `description`, `method` (or `transport` for `mcp` results), `url`, and `evaluateGuide`.

* `resourceType` — the kind of resource: `endpoint` (an HTTP endpoint) or `mcp` (an MCP). Pass it to `/v1/integrate` as the resource's `type`.
* `method` / `transport` — an `endpoint` result carries the HTTP `method`; an `mcp` result carries `transport` (the MCP transport) in its place.
* `evaluateGuide` — an evaluation of the endpoint in three parts: a brief
  summary, recommended use cases, and unsupported use cases or limitations.

`meta` carries `q`, `total`, and `nextCursor` (absent on the last page).

## Idempotency

Search is read-only and does not create or mutate data, so it is safe to retry. No idempotency key is required. Responses may still change between calls as the public catalog changes over time.

## Errors

`400` invalid input, `429` rate limited, `500` server error.

Reference: https://docs.buildwithorbit.ai/api-reference/search-public-endpoints

## Request

### Query parameters

- `limit` (integer, optional, default: 10) — Results per page. Default 10, maximum 25.
- `cursor` (string, optional) — Pagination cursor. Pass the `meta.nextCursor` value from the previous response. Omit for the first page.

### Headers

- `Orbit-Client-Name` (string, optional) — Name of the client application or agent invoking this tool (e.g. "cursor/composer-2.5", "claude/sonnet-4.6", "codex/gpt-5.6-sol", "vscode"). Used for anonymous usage analytics.

### Body (application/json)

This endpoint expects an object.

- `q` (string, required) — Free-text search: a natural language query, keywords, an API name, or a question. Matched by meaning and keyword. Capped at 512 characters; longer values return 400.

## Response

### 200

Successful Response

- `data` (list of V1SearchPostResponsesContentApplicationJsonSchemaDataItems, optional)
- `meta` (V1SearchPostResponsesContentApplicationJsonSchemaMeta, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `type` (string, optional)
- `title` (string, optional)
- `detail` (string, optional)
- `status` (integer, optional)
- `instance` (string, optional)

### 429 Too Many Requests Error

Too Many Requests

- `type` (string, optional)
- `title` (string, optional)
- `status` (integer, optional)
- `detail` (string, optional)
- `instance` (string, optional)

### 500 Internal Server Error

Internal Server Error

- `type` (string, optional)
- `title` (string, optional)
- `status` (integer, optional)
- `detail` (string, optional)
- `instance` (string, optional)

## Types

### V1SearchPostResponsesContentApplicationJsonSchemaDataItems

- `id` (string, optional) — Opaque resource identifier of the form `urn:orbit:<type>:v1:...` (`<type>` is `endpoint` or `mcp`). Pass it back verbatim to `/v1/integrate`; do not parse or construct it.
- `resourceType` (enum, optional) — Kind of resource: `endpoint` for an HTTP endpoint, `mcp` for an MCP. Pass it to `/v1/integrate` as the resource's `type`.
  - Allowed values: `endpoint`, `mcp`
- `name` (string, optional) — Human-readable name of the endpoint.
- `description` (string, optional) — What the endpoint does.
- `method` (string, optional) — HTTP method used to call the endpoint. Present for `endpoint` results; absent for `mcp` results, which carry `transport` instead.
- `transport` (string, optional) — The MCP transport (for example `streamable-http`). Present only for `mcp` results, in place of `method`.
- `url` (string, optional) — URL the endpoint is called at.
- `evaluateGuide` (string, optional) — Evaluation of the endpoint in three parts: a brief summary, recommended use cases, and unsupported use cases or limitations.

### V1SearchPostResponsesContentApplicationJsonSchemaMeta

- `q` (string, optional) — The query that produced these results.
- `total` (integer, optional) — Total number of matching results.
- `nextCursor` (string, optional) — Cursor for the next page. Absent on the last page.

## Examples

**Request**

```json
{
  "q": "Get Current Weather"
}
```

**Response**

```json
{
  "data": [
    {
      "id": "urn:orbit:endpoint:v1:1OYrNvmw0qAUVtV7jNU3tC3kuCIFbpjpfGZuyexkHTlZg60P7mpN4cYzSm9XW:weatherapi-com:current-weather-json",
      "resourceType": "endpoint",
      "name": "Get Current Weather - OpenWeatherMap",
      "description": "OpenWeatherMap API provides weather data. This request gets current weather for a city. Replace YOURAPIKEY with your actual API key from openweathermap.org",
      "method": "GET",
      "url": "https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY",
      "evaluateGuide": "Retrieves current weather data for a specified city from OpenWeatherMap. An agent can obtain conditions such as temperature and other weather details using the city and API key parameters. Use for: current weather in London, city weather lookup, temperature retrieval Not supported: forecasts, historical weather, weather alerts"
    }
  ],
  "meta": {
    "q": "Get Current Weather",
    "total": 1
  }
}
```

**SDK Code**

```python searchPublicEndpoints_example
import requests

url = "https://api.buildwithorbit.ai/v1/search"

querystring = {"cursor":"eyJmcm9tIjoxMH0=","limit":"10"}

payload = { "q": "Get Current Weather" }
headers = {
    "Orbit-Client-Name": "claude",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript searchPublicEndpoints_example
const url = 'https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10';
const options = {
  method: 'POST',
  headers: {'Orbit-Client-Name': 'claude', 'Content-Type': 'application/json'},
  body: '{"q":"Get Current Weather"}'
};

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

```go searchPublicEndpoints_example
package main

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

func main() {

	url := "https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10"

	payload := strings.NewReader("{\n  \"q\": \"Get Current Weather\"\n}")

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

	req.Header.Add("Orbit-Client-Name", "claude")
	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 searchPublicEndpoints_example
require 'uri'
require 'net/http'

url = URI("https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10")

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

request = Net::HTTP::Post.new(url)
request["Orbit-Client-Name"] = 'claude'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"q\": \"Get Current Weather\"\n}"

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

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

HttpResponse<String> response = Unirest.post("https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10")
  .header("Orbit-Client-Name", "claude")
  .header("Content-Type", "application/json")
  .body("{\n  \"q\": \"Get Current Weather\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10', [
  'body' => '{
  "q": "Get Current Weather"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'Orbit-Client-Name' => 'claude',
  ],
]);

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

```csharp searchPublicEndpoints_example
using RestSharp;

var client = new RestClient("https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10");
var request = new RestRequest(Method.POST);
request.AddHeader("Orbit-Client-Name", "claude");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"q\": \"Get Current Weather\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift searchPublicEndpoints_example
import Foundation

let headers = [
  "Orbit-Client-Name": "claude",
  "Content-Type": "application/json"
]
let parameters = ["q": "Get Current Weather"] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.buildwithorbit.ai/v1/search?cursor=eyJmcm9tIjoxMH0%3D&limit=10")! 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()
```