buildwithorbit-ai Integrate API

openapi: 3.2.0
info:
  title: Reference Integrate API
  version: 1.0.0
servers:
- url: https://api.buildwithorbit.ai
  description: https://api.buildwithorbit.ai
tags:
- name: Integrate
paths:
  /v1/integrate:
    post:
      operationId: integratePublicEndpoints
      summary: Integrate Public Endpoints
      description: '# Integrate Public Endpoints


        After 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.


        ## Request


        `POST /v1/integrate`


        ```json

        {

        "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"

        }

        ]

        }

        ```


        - `task` — what you want to accomplish (max 512 characters).

        - `resources` — the endpoints to integrate; each is an `id` from `/v1/search` plus its `type` (the result''s `resourceType`).


        Both fields are required, and every `resources` entry needs `id` and `type`


        This call takes no query parameters.


        ## Response


        The 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.

        The task brief uses the selected endpoints'' schemas and any shared variables, authentication settings, and descriptions defined by their parent APIs.


        ## Idempotency


        Integrate 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.


        ## Errors


        `400` invalid input, `404` all `id`s could not be resolved, `429` rate limited, `500` server error.'
      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
      tags:
      - Integrate
components:
  schemas:
    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
    IntegratePublicEndpointsRequestNotFoundError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      title: IntegratePublicEndpointsRequestNotFoundError
    IntegratePublicEndpointsRequestInternalServerError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      title: IntegratePublicEndpointsRequestInternalServerError
    integratePublicEndpoints_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/V1IntegratePostResponsesContentApplicationJsonSchemaDataItems'
      title: integratePublicEndpoints_Response_200
    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
    IntegratePublicEndpointsRequestTooManyRequestsError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
      title: IntegratePublicEndpointsRequestTooManyRequestsError
    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
    IntegratePublicEndpointsRequestBadRequestError:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        detail:
          type: string
        status:
          type: integer
        instance:
          type: string
      title: IntegratePublicEndpointsRequestBadRequestError