openapi: 3.1.2
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: 9bot Agent and MCP Gateway API
  summary: Public discovery and transport surface for the 9bot AI agent gateway.
  description: This OpenAPI description documents the public 9bot MCP gateway surface, OAuth and MCP discovery resources,
    health information, and generic JSON-RPC envelopes. Exact 9bot tool names and input schemas are discovered dynamically
    after OAuth authorization and depend on application scopes, authorized groups, tool policies, tenant configuration,
    and feature availability.
  version: 1.0.0
  contact:
    name: 9bot
    url: https://9bot.com.br/developers/
    email: contato@9bot.com.br
servers:
- url: https://mcp.9bot.com.br
  description: Production 9bot MCP and OAuth gateway
externalDocs:
  description: 9bot developer documentation
  url: https://9bot.com.br/developers/
tags:
- name: MCP
  description: OAuth-protected Model Context Protocol transport.
- name: Discovery
  description: Public MCP, OAuth, and registry metadata.
- name: Health
  description: Public service health information.
paths:
  /mcp:
    post:
      tags:
      - MCP
      operationId: exchangeMcpMessage
      summary: Exchange an MCP message
      description: Sends a JSON-RPC 2.0 MCP request or notification to the remote 9bot gateway. Compatible clients
        should use a current MCP SDK, negotiate the protocol version, and discover available tools after authorization.
        The gateway may return a JSON response or a request-scoped Server-Sent Events stream. The exact tool catalog
        is not enumerated in this OpenAPI file.
      security:
      - OAuthBearer: []
      parameters:
      - name: Accept
        in: header
        required: false
        description: MCP clients normally accept JSON and may accept Server-Sent Events.
        schema:
          type: string
          default: application/json, text/event-stream
      - name: MCP-Protocol-Version
        in: header
        required: false
        description: Protocol version negotiated by the MCP client and server when required.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcClientPayload'
            examples:
              listTools:
                summary: Discover tools available to the authorized application
                value:
                  jsonrpc: '2.0'
                  id: tools-1
                  method: tools/list
                  params: {}
              callDiscoveredTool:
                summary: Call a tool returned by tools/list
                value:
                  jsonrpc: '2.0'
                  id: call-1
                  method: tools/call
                  params:
                    name: <tool-name-from-tools-list>
                    arguments: {}
      responses:
        '200':
          description: JSON-RPC response or a request-scoped event stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcServerPayload'
            text/event-stream:
              schema:
                type: string
                description: A Server-Sent Events stream containing MCP JSON-RPC messages.
        '202':
          description: Notification accepted without a JSON-RPC response body.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /mcp/health:
    get:
      tags:
      - Health
      operationId: getMcpHealth
      summary: Get MCP gateway health
      description: Returns public health information for the 9bot MCP gateway.
      security: []
      responses:
        '200':
          description: Gateway health response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '500':
          $ref: '#/components/responses/ServerError'
  /.well-known/mcp:
    get:
      tags:
      - Discovery
      operationId: getMcpMetadata
      summary: Get MCP discovery metadata
      description: Returns public metadata that helps clients discover the 9bot MCP service.
      security: []
      responses:
        '200':
          description: MCP discovery metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpMetadata'
        '500':
          $ref: '#/components/responses/ServerError'
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - Discovery
      operationId: getOAuthProtectedResourceMetadata
      summary: Get OAuth protected resource metadata
      description: Returns RFC 9728-style discovery metadata for the 9bot protected resource.
      security: []
      responses:
        '200':
          description: OAuth protected resource metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthProtectedResourceMetadata'
        '500':
          $ref: '#/components/responses/ServerError'
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - Discovery
      operationId: getOAuthAuthorizationServerMetadata
      summary: Get OAuth authorization server metadata
      description: Returns OAuth server endpoints and supported authorization capabilities.
      security: []
      responses:
        '200':
          description: OAuth authorization server metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAuthorizationServerMetadata'
        '500':
          $ref: '#/components/responses/ServerError'
  /server.json:
    get:
      tags:
      - Discovery
      operationId: getMcpRegistryManifest
      summary: Get the MCP Registry server manifest
      description: Returns the public server manifest used for MCP registry and client discovery.
      security: []
      responses:
        '200':
          description: MCP server manifest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpServerManifest'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    OAuthBearer:
      type: http
      scheme: bearer
      bearerFormat: OAuth 2.1 access token
      description: Obtain authorization using the protected resource and authorization server metadata. Exact scopes
        and endpoints are advertised by the production metadata.
  schemas:
    JsonRpcId:
      oneOf:
      - type: string
      - type: integer
      description: A client-selected JSON-RPC request identifier.
    JsonRpcRequest:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        method:
          type: string
          minLength: 1
        params:
          oneOf:
          - type: object
          - type: array
          description: Method-specific parameters.
    JsonRpcNotification:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        method:
          type: string
          minLength: 1
        params:
          oneOf:
          - type: object
          - type: array
          description: Method-specific parameters.
    JsonRpcSuccessResponse:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - result
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          $ref: '#/components/schemas/JsonRpcId'
        result:
          description: Method-specific result.
    JsonRpcError:
      type: object
      additionalProperties: false
      required:
      - code
      - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          description: Optional structured error information.
    JsonRpcErrorResponse:
      type: object
      additionalProperties: false
      required:
      - jsonrpc
      - id
      - error
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - $ref: '#/components/schemas/JsonRpcId'
          - type: 'null'
        error:
          $ref: '#/components/schemas/JsonRpcError'
    JsonRpcClientMessage:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcRequest'
      - $ref: '#/components/schemas/JsonRpcNotification'
    JsonRpcClientPayload:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcClientMessage'
      - type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/JsonRpcClientMessage'
    JsonRpcServerMessage:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcSuccessResponse'
      - $ref: '#/components/schemas/JsonRpcErrorResponse'
      - $ref: '#/components/schemas/JsonRpcNotification'
      - $ref: '#/components/schemas/JsonRpcRequest'
    JsonRpcServerPayload:
      oneOf:
      - $ref: '#/components/schemas/JsonRpcServerMessage'
      - type: array
        minItems: 1
        items:
          $ref: '#/components/schemas/JsonRpcServerMessage'
    HealthResponse:
      type: object
      description: Public service health payload. Additional fields may be present.
      additionalProperties: true
      properties:
        status:
          type: string
          examples:
          - ok
        service:
          type: string
          examples:
          - 9bot-mcp
        version:
          type: string
        timestamp:
          type: string
          format: date-time
    McpMetadata:
      type: object
      description: Public MCP discovery metadata. The production response is authoritative.
      additionalProperties: true
      properties:
        name:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        endpoint:
          type: string
          format: uri
        authorization:
          type: object
          additionalProperties: true
    OAuthProtectedResourceMetadata:
      type: object
      description: OAuth protected resource metadata. Additional RFC fields may be present.
      additionalProperties: true
      required:
      - resource
      properties:
        resource:
          type: string
          format: uri
        authorization_servers:
          type: array
          items:
            type: string
            format: uri
        scopes_supported:
          type: array
          items:
            type: string
        bearer_methods_supported:
          type: array
          items:
            type: string
        resource_documentation:
          type: string
          format: uri
    OAuthAuthorizationServerMetadata:
      type: object
      description: OAuth authorization server metadata. The production response is authoritative.
      additionalProperties: true
      required:
      - issuer
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        registration_endpoint:
          type: string
          format: uri
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
    McpServerManifest:
      type: object
      description: MCP Registry server manifest. Additional schema fields may be present.
      additionalProperties: true
      required:
      - name
      - version
      properties:
        $schema:
          type: string
          format: uri
        name:
          type: string
        title:
          type: string
        description:
          type: string
        version:
          type: string
        websiteUrl:
          type: string
          format: uri
        remotes:
          type: array
          items:
            type: object
            additionalProperties: true
    HttpError:
      type: object
      additionalProperties: true
      properties:
        error:
          type: string
        error_description:
          type: string
        message:
          type: string
        request_id:
          type: string
  responses:
    BadRequest:
      description: Invalid request, media type, protocol envelope, or parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Unauthorized:
      description: OAuth authorization is missing, expired, invalid, or not accepted.
      headers:
        WWW-Authenticate:
          description: Bearer challenge and protected resource metadata hint when available.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    Forbidden:
      description: The application lacks the required scope, group access, tool permission, or tenant policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    RateLimited:
      description: The request exceeded a gateway, tenant, token, tool, or IP rate limit.
      headers:
        Retry-After:
          description: When present, the delay before a retry.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    ServerError:
      description: Temporary gateway or dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
x-9bot-ai-interfaces:
  mcp: https://mcp.9bot.com.br/mcp
  webmcp: https://9bot.com.br/developers/webmcp/
  llms: https://9bot.com.br/llms.txt
  llmsFull: https://9bot.com.br/llms-full.txt
