{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/v1/search":{"post":{"operationId":"searchPublicEndpoints","summary":"Search Public Endpoints","description":"# Search Public Endpoints\n\nDescribe 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.\n\n## Request\n\n`POST /v1/search`\n\n```json\n{ \"q\": \"Get Current Weather\" }\n```\n\n```json\n{ \"q\": \"Add tracking details for an existing paypal order\" }\n```\n\n`q` is required and capped at 512 characters. No other body field is accepted; unknown fields return `400`.\n\n**Query parameters**\n\n- `limit` — results per page (default 10, max 25)\n- `cursor` — pass `meta.nextCursor` from the previous response\n\nPagination stops at 40 results total; a cursor past 40 is rejected.\n\n## Response\n\nEach result carries `id`, `resourceType`, `name`, `description`, `method` (or `transport` for `mcp` results), `url`, and `evaluateGuide`.\n\n- `resourceType` — the kind of resource: `endpoint` (an HTTP endpoint) or `mcp` (an MCP). Pass it to `/v1/integrate` as the resource's `type`.\n- `method` / `transport` — an `endpoint` result carries the HTTP `method`; an `mcp` result carries `transport` (the MCP transport) in its place.\n- `evaluateGuide` — an evaluation of the endpoint in three parts: a brief\n  summary, recommended use cases, and unsupported use cases or limitations.\n\n\n`meta` carries `q`, `total`, and `nextCursor` (absent on the last page).\n\n## Idempotency\n\nSearch 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.\n\n## Errors\n\n`400` invalid input, `429` rate limited, `500` server error.\n","parameters":[{"name":"limit","in":"query","description":"Results per page. Default 10, maximum 25.","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"examples":{"searchPublicEndpoints_example":{"value":10,"summary":"searchPublicEndpoints_example"},"example-2":{"value":10},"example-3":{"value":10},"example-4":{"value":10}}},{"name":"cursor","in":"query","description":"Pagination cursor. Pass the `meta.nextCursor` value from the previous response. Omit for the first page.","required":false,"schema":{"type":"string"},"examples":{"searchPublicEndpoints_example":{"value":"eyJmcm9tIjoxMH0=","summary":"searchPublicEndpoints_example"},"example-2":{"value":"string"},"example-3":{"value":"string"},"example-4":{"value":"string"}}},{"name":"Orbit-Client-Name","in":"header","description":"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.","required":false,"schema":{"type":"string","maxLength":128},"examples":{"searchPublicEndpoints_example":{"value":"claude","summary":"searchPublicEndpoints_example"},"example-2":{"value":"string"},"example-3":{"value":"string"},"example-4":{"value":"string"}}}],"responses":{"200":{"description":"Successful Response","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/searchPublicEndpoints_Response_200"},"examples":{"searchPublicEndpoints_example":{"value":{"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}},"summary":"searchPublicEndpoints_example"}}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestBadRequestError"},"examples":{"searchPublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Bad Request","detail":"body must NOT have additional properties: 'query'","status":400,"instance":"/v1/search"}}}}}},"429":{"description":"Too Many Requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","required":true,"schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestTooManyRequestsError"},"examples":{"searchPublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Too Many Requests","status":429,"detail":"Rate limit exceeded. Retry after the delay in the Retry-After header.","instance":"/v1/search"}}}}}},"500":{"description":"Internal Server Error","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestInternalServerError"},"examples":{"searchPublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Something went wrong","status":500,"detail":"Something went wrong while searching for endpoints","instance":"/v1/search"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"q":{"type":"string","minLength":1,"maxLength":512,"description":"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."}},"required":["q"]},"examples":{"searchPublicEndpoints_example":{"value":{"q":"Get Current Weather"},"summary":"searchPublicEndpoints_example"},"example-2":{"value":{"q":"string"}},"example-3":{"value":{"q":"string"}},"example-4":{"value":{"q":"string"}}}}}}}},"/v1/integrate":{"post":{"operationId":"integratePublicEndpoints","summary":"Integrate Public Endpoints","description":"# Integrate Public Endpoints\n\nAfter selecting endpoints from `/v1/search`, send them to `/v1/integrate` along with the task you want to accomplish. It returns a **task brief** with the information and steps needed to call the selected endpoints.\n\n## Request\n\n`POST /v1/integrate`\n\n```json\n{\n  \"task\": \"Build an app to post current weather to Slack\",\n  \"resources\": [\n        {\n            \"id\": \"urn:orbit:endpoint:v1:1OYrNvmw0qAUVtV7jNU3tC3kuCIFbpjpfGZuyexkHTlZg60P7mpN4cYzSm9XW:weatherapi-com:current-weather-json\",\n            \"type\": \"endpoint\"\n        },\n        {\n            \"id\": \"urn:orbit:endpoint:v1:1Jgb5F43F8b9al2a64G1srYRVxJ3SKnSepsgceU9aKzl1nnJeNHWFxEudTUMG:slack:send-message-to-slack\",\n            \"type\": \"endpoint\"\n        }\n    ]\n}\n```\n\n- `task` — what you want to accomplish (max 512 characters).\n- `resources` — the endpoints to integrate; each is an `id` from `/v1/search` plus its `type` (the result's `resourceType`).\n\nBoth fields are required, and every `resources` entry needs `id` and `type`\n\nThis call takes no query parameters.\n\n## Response\n\nThe response contains one `data` entry with a `taskBrief`. The brief includes authentication requirements, base URLs, request steps, parameters, expected responses, dependencies between steps, and important considerations.\nThe task brief uses the selected endpoints' schemas and any shared variables, authentication settings, and descriptions defined by their parent APIs.\n\n## Idempotency\n\nIntegrate is read-only: it generates a task brief from the referenced endpoints and never creates or mutates data, so it is safe to retry. No idempotency key is required. The generated brief's wording may vary between otherwise identical calls.\n\n## Errors\n\n`400` invalid input, `404` all `id`s could not be resolved, `429` rate limited, `500` server error.\n","parameters":[{"name":"Orbit-Client-Name","in":"header","description":"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.","required":false,"schema":{"type":"string","maxLength":128},"examples":{"integratePublicEndpoints_example":{"value":"claude","summary":"integratePublicEndpoints_example"},"example-2":{"value":"string"},"example-3":{"value":"string"},"example-4":{"value":"string"},"example-5":{"value":"string"}}}],"responses":{"200":{"description":"Successful Response","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/integratePublicEndpoints_Response_200"},"examples":{"integratePublicEndpoints_example":{"value":{"data":[{"taskBrief":"TASK BRIEF: Two independent calls supporting a weather-to-Slack app: retrieve London weather and post a message to Slack (OpenWeatherMap and Slack Web API)\nFIT\n  Fully. The supplied requests provide both capabilities: retrieving current weather and posting a Slack message. The weather request is used to supply the content for the Slack message; no supplied requests are irrelevant.\n\nAUTH\n  OpenWeatherMap: API key supplied as the required `appid` query parameter; replace `YOUR_API_KEY` with the actual key.\n  Slack: bot token supplied in the `token` form field/header value as `{{bot_token}}`, requiring the `chat:write` scope. The Slack collection also specifies bearer authentication using the same `{{bot_token}}` credential; the request explicitly defines the `token` field.\n\nBASE URL\n  https://api.openweathermap.org  step 1\n  https://slack.com step 2\n\nSTEPS\n  1. GET /data/2.5/weather\n    Params:\n      q: required string query parameter  `London`\n      appid: required string query parameter `YOUR_API_KEY` (replace with your OpenWeatherMap API key)\n    Returns:\n      No saved response example; the request is intended to return current weather data for the specified city.\n    Threading:\n      None\n\n  2. POST /api/chat.postMessage\n    Params (application/x-www-form-urlencoded body):\n      token: required string authentication field  `{{bot_token}}`\n      channel: required string  `<string>` or a channel/private-group/IM channel identifier\n      text: string message text  `test`; replace with the weather summary to post\n      Optional disabled fields include `as_user`, `attachments`, `blocks`, `icon_emoji`, `icon_url`, `link_names`, `mrkdwn`, `parse`, `reply_broadcast`, `thread_ts`, `unfurl_links`, `unfurl_media`, and `username`.\n    Returns:\n      HTTP 200 OK with JSON fields `ok` (boolean), `channel` (string), `ts` (string), and `message` (object). The message example includes `text`, `type`, and `ts`, plus optional attachments and blocks.\n    Threading:\n      None\n\nGOTCHAS\n  - Step 1 uses `appid` in the query string, not an authorization header.\n  - Step 2 must use `application/x-www-form-urlencoded`, not JSON."}]},"summary":"integratePublicEndpoints_example"}}}}},"400":{"description":"Bad Request","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestBadRequestError"},"examples":{"integratePublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Bad Request","detail":"body must have required property 'task'","status":400,"instance":"/v1/integrate"}}}}}},"404":{"description":"Not Found","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestNotFoundError"},"examples":{"integratePublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Not Found","status":404,"detail":"No resource could be resolved for one or more of the provided ids","instance":"/v1/integrate"}}}}}},"429":{"description":"Too Many Requests","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","required":true,"schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestTooManyRequestsError"},"examples":{"integratePublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Too Many Requests","status":429,"detail":"Rate limit exceeded. Retry after the delay in the Retry-After header.","instance":"/v1/integrate"}}}}}},"500":{"description":"Internal Server Error","headers":{"RateLimit-Limit":{"description":"Requests permitted in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current rate-limit window.","required":true,"schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Unix timestamp (seconds since epoch) at which the current rate-limit window resets.","required":true,"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestInternalServerError"},"examples":{"integratePublicEndpoints_error_example":{"value":{"type":"about:blank","title":"Something went wrong","status":500,"detail":"Something went wrong while getting integration details for the endpoint","instance":"/v1/integrate"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"task":{"type":"string","pattern":"\\S","minLength":1,"maxLength":512},"resources":{"type":"array","items":{"$ref":"#/components/schemas/V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItems"}}},"required":["task","resources"]},"examples":{"integratePublicEndpoints_example":{"value":{"task":"Build an app to post current weather to slack","resources":[{"id":"urn:orbit:endpoint:v1:1OYrNvmw0qAUVtV7jNU3tC3kuCIFbpjpfGZuyexkHTlZg60P7mpN4cYzSm9XW:weatherapi-com:current-weather-json","type":"endpoint"},{"id":"urn:orbit:endpoint:v1:1Jgb5F43F8b9al2a64G1srYRVxJ3SKnSepsgceU9aKzl1nnJeNHWFxEudTUMG:slack:send-message-to-slack","type":"endpoint"}]},"summary":"integratePublicEndpoints_example"},"example-2":{"value":{"task":"string","resources":[{"id":"string","type":"endpoint"}]}},"example-3":{"value":{"task":"string","resources":[{"id":"string","type":"endpoint"}]}},"example-4":{"value":{"task":"string","resources":[{"id":"string","type":"endpoint"}]}},"example-5":{"value":{"task":"string","resources":[{"id":"string","type":"endpoint"}]}}}}}}}}},"servers":[{"url":"https://api.buildwithorbit.ai","description":"https://api.buildwithorbit.ai"}],"components":{"schemas":{"V1SearchPostResponsesContentApplicationJsonSchemaDataItemsResourceType":{"type":"string","enum":["endpoint","mcp"],"description":"Kind of resource: `endpoint` for an HTTP endpoint, `mcp` for an MCP. Pass it to `/v1/integrate` as the resource's `type`.","title":"V1SearchPostResponsesContentApplicationJsonSchemaDataItemsResourceType"},"V1SearchPostResponsesContentApplicationJsonSchemaDataItems":{"type":"object","properties":{"id":{"type":"string","description":"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":{"$ref":"#/components/schemas/V1SearchPostResponsesContentApplicationJsonSchemaDataItemsResourceType","description":"Kind of resource: `endpoint` for an HTTP endpoint, `mcp` for an MCP. Pass it to `/v1/integrate` as the resource's `type`."},"name":{"type":"string","description":"Human-readable name of the endpoint."},"description":{"type":"string","description":"What the endpoint does."},"method":{"type":"string","description":"HTTP method used to call the endpoint. Present for `endpoint` results; absent for `mcp` results, which carry `transport` instead."},"transport":{"type":"string","description":"The MCP transport (for example `streamable-http`). Present only for `mcp` results, in place of `method`."},"url":{"type":"string","format":"uri","description":"URL the endpoint is called at."},"evaluateGuide":{"type":"string","description":"Evaluation of the endpoint in three parts: a brief summary, recommended use cases, and unsupported use cases or limitations."}},"title":"V1SearchPostResponsesContentApplicationJsonSchemaDataItems"},"V1SearchPostResponsesContentApplicationJsonSchemaMeta":{"type":"object","properties":{"q":{"type":"string","description":"The query that produced these results."},"total":{"type":"integer","description":"Total number of matching results."},"nextCursor":{"type":"string","description":"Cursor for the next page. Absent on the last page."}},"title":"V1SearchPostResponsesContentApplicationJsonSchemaMeta"},"searchPublicEndpoints_Response_200":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V1SearchPostResponsesContentApplicationJsonSchemaDataItems"}},"meta":{"$ref":"#/components/schemas/V1SearchPostResponsesContentApplicationJsonSchemaMeta"}},"title":"searchPublicEndpoints_Response_200"},"SearchPublicEndpointsRequestBadRequestError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"},"instance":{"type":"string"}},"title":"SearchPublicEndpointsRequestBadRequestError"},"SearchPublicEndpointsRequestTooManyRequestsError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"title":"SearchPublicEndpointsRequestTooManyRequestsError"},"SearchPublicEndpointsRequestInternalServerError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"title":"SearchPublicEndpointsRequestInternalServerError"},"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItemsType":{"type":"string","enum":["endpoint","mcp"],"description":"The resource's type, as returned in `/v1/search`'s `resourceType` — `endpoint` (an HTTP endpoint) or `mcp` (an MCP).","title":"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItemsType"},"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItems":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItemsType","description":"The resource's type, as returned in `/v1/search`'s `resourceType` — `endpoint` (an HTTP endpoint) or `mcp` (an MCP)."}},"required":["id","type"],"title":"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItems"},"V1IntegratePostResponsesContentApplicationJsonSchemaDataItems":{"type":"object","properties":{"taskBrief":{"type":"string","description":"Multi-line task brief with the auth, base URL, steps, and gotchas needed to call the selected endpoints."}},"title":"V1IntegratePostResponsesContentApplicationJsonSchemaDataItems"},"integratePublicEndpoints_Response_200":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/V1IntegratePostResponsesContentApplicationJsonSchemaDataItems"}}},"title":"integratePublicEndpoints_Response_200"},"IntegratePublicEndpointsRequestBadRequestError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"},"instance":{"type":"string"}},"title":"IntegratePublicEndpointsRequestBadRequestError"},"IntegratePublicEndpointsRequestNotFoundError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"title":"IntegratePublicEndpointsRequestNotFoundError"},"IntegratePublicEndpointsRequestTooManyRequestsError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"title":"IntegratePublicEndpointsRequestTooManyRequestsError"},"IntegratePublicEndpointsRequestInternalServerError":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"title":"IntegratePublicEndpointsRequestInternalServerError"}}}}