buildwithorbit-ai Search API

openapi: 3.2.0
info:
  title: Reference Search API
  version: 1.0.0
servers:
- url: https://api.buildwithorbit.ai
  description: https://api.buildwithorbit.ai
tags:
- name: Search
paths:
  /v1/search:
    post:
      operationId: searchPublicEndpoints
      summary: Search Public Endpoints
      description: '# 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.'
      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
      tags:
      - Search
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
    SearchPublicEndpointsRequestBadRequestError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        detail:
          type: string
        status:
          type: integer
        instance:
          type: string
      title: SearchPublicEndpointsRequestBadRequestError
    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
    SearchPublicEndpointsRequestTooManyRequestsError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      title: SearchPublicEndpointsRequestTooManyRequestsError
    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
    SearchPublicEndpointsRequestInternalServerError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      title: SearchPublicEndpointsRequestInternalServerError
    searchPublicEndpoints_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/V1SearchPostResponsesContentApplicationJsonSchemaDataItems'
        meta:
          $ref: '#/components/schemas/V1SearchPostResponsesContentApplicationJsonSchemaMeta'
      title: searchPublicEndpoints_Response_200