{"openapi":"3.1.0","info":{"title":"API Reference","version":"1.0.0"},"paths":{"/v1/search":{"post":{"operationId":"search-public-endpoints","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`, `url`, and `evaluateGuide`;.\n\n- `resourceType` — the kind of entity, for example `endpoint`. Pass it to `/v1/integrate` as the resource's `type`.\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}},{"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"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/searchPublicEndpoints_Response_200"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestBadRequestError"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestTooManyRequestsError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPublicEndpointsRequestInternalServerError"}}}}},"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"]}}}}}},"/v1/integrate":{"post":{"operationId":"integrate-public-endpoints","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","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/integratePublicEndpoints_Response_200"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestBadRequestError"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestNotFoundError"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestTooManyRequestsError"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegratePublicEndpointsRequestInternalServerError"}}}}},"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"]}}}}}}},"servers":[{"url":"https://api.buildwithorbit.ai","description":"https://api.buildwithorbit.ai"}],"components":{"schemas":{"V1SearchPostResponsesContentApplicationJsonSchemaDataItems":{"type":"object","properties":{"id":{"type":"string","description":"Opaque endpoint identifier of the form `urn:orbit:endpoint:v1:...`. Pass it back verbatim to `/v1/integrate`; do not parse or construct it."},"resourceType":{"type":"string","description":"Kind of entity, for example `endpoint`. 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."},"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"],"title":"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItemsType"},"V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItems":{"type":"object","properties":{"id":{"type":"string"},"type":{"$ref":"#/components/schemas/V1IntegratePostRequestBodyContentApplicationJsonSchemaResourcesItemsType"}},"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"}}}}