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