{
  "openapi": "3.1.0",
  "info": {
    "title": "Arete Documentation API",
    "summary": "HTTP API for the Arete documentation MCP server",
    "description": "Machine-readable access to docs.arete.run. GET /mcp returns the documentation MCP descriptor. POST /mcp is JSON-RPC 2.0 Streamable HTTP for the search_docs and fetch_page tools. This is a documentation API, not the hosted Arete catalog or transaction API.",
    "version": "1.0.0",
    "contact": {
      "name": "Arete documentation",
      "url": "https://docs.arete.run/contact"
    }
  },
  "servers": [
    {
      "url": "https://docs.arete.run",
      "description": "Production documentation origin"
    }
  ],
  "tags": [
    {
      "name": "mcp",
      "description": "Arete documentation MCP server (search_docs, fetch_page)"
    },
    {
      "name": "discovery",
      "description": "OpenAPI and well-known discovery documents"
    }
  ],
  "paths": {
    "/mcp": {
      "get": {
        "operationId": "getAreteDocsMcpDescriptor",
        "tags": [
          "mcp"
        ],
        "summary": "Get the Arete documentation MCP descriptor",
        "description": "Returns the documentation MCP server descriptor: endpoint, protocol version, search_docs and fetch_page input schemas, and skill.md resource. Clients that send Accept: text/event-stream receive the Streamable HTTP GET stream instead of this JSON document.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "application/json (default) for the descriptor, or text/event-stream for Streamable HTTP GET.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MCP descriptor for the Arete documentation server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpDescriptor"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postAreteDocsMcpJsonRpc",
        "tags": [
          "mcp"
        ],
        "summary": "Call Arete documentation MCP tools over JSON-RPC",
        "description": "JSON-RPC 2.0 Streamable HTTP transport for the Arete documentation MCP server. Supported tools are search_docs and fetch_page. Invalid JSON, missing Content-Type, and unsupported methods return a structured JSON error with code, message, and hint.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC success or JSON-RPC error payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          },
          "400": {
            "description": "Request was not valid JSON-RPC",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type was not application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mcp/sse": {
      "get": {
        "operationId": "getAreteDocsMcpDescriptorAlias",
        "tags": [
          "mcp"
        ],
        "summary": "Legacy alias for GET /mcp",
        "description": "Same descriptor as getAreteDocsMcpDescriptor. Prefer https://docs.arete.run/mcp.",
        "responses": {
          "200": {
            "description": "MCP descriptor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/McpDescriptor"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postAreteDocsMcpJsonRpcAlias",
        "tags": [
          "mcp"
        ],
        "summary": "Legacy alias for POST /mcp",
        "description": "Same JSON-RPC transport as postAreteDocsMcpJsonRpc. Prefer https://docs.arete.run/mcp.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JsonRpcRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcResponse"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getAreteDocsOpenApiSpec",
        "tags": [
          "discovery"
        ],
        "summary": "Get this OpenAPI document",
        "description": "Returns the OpenAPI 3.1 description of the Arete documentation HTTP API, including unique operationIds, typed parameters, and JSON error schemas for function-calling clients.",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "hint"
            ],
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code",
                "examples": [
                  "not_found",
                  "method_not_allowed",
                  "invalid_request",
                  "unsupported_media_type"
                ]
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of what failed"
              },
              "hint": {
                "type": "string",
                "description": "How an agent should recover: llms.txt, OpenAPI, or MCP tools"
              }
            }
          }
        }
      },
      "McpDescriptor": {
        "type": "object",
        "required": [
          "name",
          "endpoint",
          "tools"
        ],
        "properties": {
          "name": {
            "type": "string",
            "examples": [
              "arete-docs"
            ]
          },
          "description": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "protocolVersion": {
            "type": "string"
          },
          "transport": {
            "type": "string",
            "examples": [
              "streamable-http"
            ]
          },
          "endpoint": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://docs.arete.run/mcp"
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/McpTool"
            }
          }
        }
      },
      "McpTool": {
        "type": "object",
        "required": [
          "name",
          "description",
          "inputSchema"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "search_docs",
              "fetch_page"
            ]
          },
          "description": {
            "type": "string"
          },
          "inputSchema": {
            "type": "object"
          }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": [
          "jsonrpc",
          "method"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "method": {
            "type": "string",
            "description": "MCP JSON-RPC method such as initialize, tools/list, or tools/call"
          },
          "params": {
            "type": "object"
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "type": "object"
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              },
              "data": true
            }
          }
        }
      }
    }
  }
}