openapi: 3.0.0
info:
  description: Create and manage MCP gateways scoped to organizations and projects. Gateways expose tool catalogs to MCP clients.
  title: Arcade Gateways API
  contact:
    name: Arcade
    url: https://arcade.dev
    email: contact@arcade.dev
  version: 0.1.0
paths:
  /v1/orgs/{org_id}/projects/{project_id}/gateways:
    get:
      security:
      - Bearer: []
      description: Returns a paginated list of gateways for the current project
      tags:
      - Gateways
      summary: List Gateways
      operationId: project-gateways-list
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      - description: 'Number of items to return (default: 25, max: 100)'
        name: limit
        in: query
        schema:
          type: integer
      - description: 'Offset from the start of the list (default: 0)'
        name: offset
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.OffsetPage-schemas_GatewayResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
    post:
      security:
      - Bearer: []
      description: Creates a new gateway in the current project
      tags:
      - Gateways
      summary: Create a Gateway
      operationId: project-gateways-create
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schemas.CreateGatewayRequest'
        description: Gateway configuration
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.GatewayResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
  /v1/orgs/{org_id}/projects/{project_id}/gateways/slug:
    post:
      security:
      - Bearer: []
      description: Checks whether a gateway slug is available for use
      tags:
      - Gateways
      summary: Check Gateway Slug Availability
      operationId: project-gateways-slug-info
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schemas.SlugInfoRequest'
        description: Slug info request
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.SlugInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
  /v1/orgs/{org_id}/projects/{project_id}/gateways/{gateway_id}:
    get:
      security:
      - Bearer: []
      description: Returns a single gateway by ID
      tags:
      - Gateways
      summary: Get a Gateway
      operationId: project-gateways-get
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      - description: Gateway ID
        name: gateway_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.GatewayResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
    put:
      security:
      - Bearer: []
      description: Replaces the full configuration of an existing gateway
      tags:
      - Gateways
      summary: Update a Gateway
      operationId: project-gateways-update
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      - description: Gateway ID
        name: gateway_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schemas.UpdateGatewayRequest'
        description: Gateway configuration
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.GatewayResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
    delete:
      security:
      - Bearer: []
      description: Deletes a gateway by ID
      tags:
      - Gateways
      summary: Delete a Gateway
      operationId: project-gateways-delete
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      - description: Gateway ID
        name: gateway_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
    patch:
      security:
      - Bearer: []
      description: Partially updates an existing gateway configuration
      tags:
      - Gateways
      summary: Patch a Gateway
      operationId: project-gateways-patch
      parameters:
      - description: Organization ID
        name: org_id
        in: path
        required: true
        schema:
          type: string
      - description: Project ID
        name: project_id
        in: path
        required: true
        schema:
          type: string
      - description: Gateway ID
        name: gateway_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/schemas.PatchGatewayRequest'
        description: Gateway fields to update
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.GatewayResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/schemas.Error'
externalDocs:
  description: Documentation
  url: https://docs.arcade.dev
servers:
- url: https://api.arcade.dev
components:
  securitySchemes:
    Bearer:
      description: 'Enter your API key or API token in the format: Bearer <token>'
      type: apiKey
      name: Authorization
      in: header
  schemas:
    identity.BindingType:
      type: string
      enum:
      - static
      - tenant
      - project
      - account
      x-enum-varnames:
      - StaticBindingType
      - TenantBindingType
      - ProjectBindingType
      - AccountBindingType
    schemas.BindingResponse:
      type: object
      properties:
        id:
          type: string
        type:
          $ref: '#/components/schemas/identity.BindingType'
    schemas.CreateDiscoveryRequest:
      type: object
      properties:
        allowed_classes:
          type: array
          maxItems: 10
          items:
            type: string
        enabled:
          type: boolean
        pinned_asset_keys:
          type: array
          maxItems: 500
          items:
            type: string
    schemas.CreateGatewayRequest:
      type: object
      required:
      - name
      properties:
        allowed_passthrough_headers:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
        auth_type:
          type: string
          enum:
          - arcade
          - arcade_header
          - user_source
        consent_skip_client_ids:
          type: array
          maxItems: 64
          uniqueItems: true
          items:
            type: string
        description:
          type: string
          maxLength: 1000
        instructions:
          type: string
          maxLength: 5000
        name:
          type: string
          maxLength: 256
        slug:
          type: string
          maxLength: 256
        status:
          type: string
        tool_filter:
          $ref: '#/components/schemas/schemas.CreateToolFilterRequest'
        user_source_id:
          type: string
    schemas.CreateToolFilterRequest:
      type: object
      properties:
        allowed_tools:
          description: 'Qualified tool names allowed through this gateway. Each entry must be in the

            "Provider.ToolName" form (for example, "Google.SendEmail"). Versioned tool

            names are not yet supported.'
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: string
        discovery:
          $ref: '#/components/schemas/schemas.CreateDiscoveryRequest'
    schemas.DiscoveryResponse:
      type: object
      properties:
        allowed_classes:
          type: array
          items:
            type: string
        enabled:
          type: boolean
        pinned_asset_keys:
          type: array
          items:
            type: string
    schemas.Error:
      type: object
      properties:
        message:
          type: string
        name:
          type: string
    schemas.GatewayResponse:
      type: object
      properties:
        allowed_passthrough_headers:
          type: array
          items:
            type: string
        auth_type:
          type: string
        binding:
          $ref: '#/components/schemas/schemas.BindingResponse'
        consent_skip_client_ids:
          type: array
          items:
            type: string
        created_at:
          type: string
        description:
          type: string
        id:
          type: string
        instructions:
          type: string
        name:
          type: string
        slug:
          type: string
        status:
          type: string
        tool_filter:
          $ref: '#/components/schemas/schemas.ToolFilterResponse'
        updated_at:
          type: string
        user_source_id:
          type: string
    schemas.OffsetPage-schemas_GatewayResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/schemas.GatewayResponse'
        limit:
          type: integer
        offset:
          type: integer
        page_count:
          type: integer
        total_count:
          type: integer
    schemas.PatchDiscoveryRequest:
      type: object
      properties:
        allowed_classes:
          type: array
          maxItems: 10
          items:
            type: string
        enabled:
          type: boolean
        pinned_asset_keys:
          type: array
          maxItems: 500
          items:
            type: string
    schemas.PatchGatewayRequest:
      type: object
      properties:
        allowed_passthrough_headers:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
        auth_type:
          type: string
          enum:
          - arcade
          - arcade_header
          - user_source
        consent_skip_client_ids:
          type: array
          maxItems: 64
          uniqueItems: true
          items:
            type: string
        description:
          type: string
          maxLength: 1000
        instructions:
          type: string
          maxLength: 5000
        name:
          type: string
          maxLength: 256
          minLength: 1
        slug:
          type: string
          maxLength: 256
        status:
          type: string
        tool_filter:
          $ref: '#/components/schemas/schemas.PatchToolFilterRequest'
        user_source_id:
          type: string
    schemas.PatchToolFilterRequest:
      type: object
      properties:
        allowed_tools:
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: string
        discovery:
          $ref: '#/components/schemas/schemas.PatchDiscoveryRequest'
    schemas.SlugInfoRequest:
      type: object
      required:
      - slug
      properties:
        slug:
          type: string
          maxLength: 256
    schemas.SlugInfoResponse:
      type: object
      properties:
        available:
          type: boolean
    schemas.ToolFilterResponse:
      type: object
      properties:
        allowed_tools:
          type: array
          items:
            type: string
        discovery:
          $ref: '#/components/schemas/schemas.DiscoveryResponse'
    schemas.UpdateDiscoveryRequest:
      type: object
      properties:
        allowed_classes:
          type: array
          maxItems: 10
          items:
            type: string
        enabled:
          type: boolean
        pinned_asset_keys:
          type: array
          maxItems: 500
          items:
            type: string
    schemas.UpdateGatewayRequest:
      type: object
      required:
      - id
      - name
      properties:
        allowed_passthrough_headers:
          type: array
          maxItems: 100
          uniqueItems: true
          items:
            type: string
        auth_type:
          type: string
          enum:
          - arcade
          - arcade_header
          - user_source
        consent_skip_client_ids:
          type: array
          maxItems: 64
          uniqueItems: true
          items:
            type: string
        description:
          type: string
          maxLength: 1000
        id:
          type: string
        instructions:
          type: string
          maxLength: 5000
        name:
          type: string
          maxLength: 256
        slug:
          type: string
          maxLength: 256
        status:
          type: string
        tool_filter:
          $ref: '#/components/schemas/schemas.UpdateToolFilterRequest'
        user_source_id:
          type: string
    schemas.UpdateToolFilterRequest:
      type: object
      properties:
        allowed_tools:
          description: 'Qualified tool names allowed through this gateway. Each entry must be in the

            "Provider.ToolName" form (for example, "Google.SendEmail"). Versioned tool

            names are not yet supported.'
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: string
        discovery:
          $ref: '#/components/schemas/schemas.UpdateDiscoveryRequest'