{
  "openapi": "3.1.0",
  "info": {
    "title": "AGIP Public Content and Discovery API",
    "version": "1.1.0",
    "description": "Public, read-only discovery for the AGIP website and its Model Context Protocol service. No OAuth or OIDC grant is required because these endpoints expose published public content only."
  },
  "servers": [
    { "url": "https://www.agip.com", "description": "AGIP production website" }
  ],
  "security": [],
  "paths": {
    "/status": {
      "get": {
        "operationId": "getStatus",
        "summary": "Get the public service status",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is available",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpLanding",
        "summary": "Get the MCP service landing response",
        "security": [],
        "responses": {
          "200": {
            "description": "MCP service information",
            "content": { "text/plain": { "schema": { "type": "string" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      },
      "post": {
        "operationId": "sendMcpRequest",
        "summary": "Send a stateless MCP Streamable HTTP request",
        "description": "The request and response follow the Model Context Protocol JSON-RPC envelope. All AGIP tools are read-only, non-destructive and idempotent. JSON-RPC notifications are acknowledged with HTTP 202.",
        "security": [],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional unique retry key. Safe for all AGIP calls because every published tool is read-only and idempotent.",
            "schema": { "type": "string", "minLength": 8, "maxLength": 200 }
          },
          {
            "name": "Prefer",
            "in": "header",
            "required": false,
            "description": "Use respond-async for a JSON-RPC notification acknowledgement.",
            "schema": { "type": "string", "examples": ["respond-async"] }
          }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } }
        },
        "responses": {
          "200": {
            "description": "MCP JSON-RPC response or Streamable HTTP event stream",
            "headers": {
              "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "202": {
            "description": "JSON-RPC notification accepted; notifications intentionally have no response body",
            "headers": {
              "Location": { "description": "Optional status URL when background work is created", "schema": { "type": "string", "format": "uri-reference" } },
              "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" },
              "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" },
              "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }
            }
          },
          "400": {
            "description": "Invalid MCP or JSON-RPC request",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "operationId": "getJobStatus",
        "summary": "Get the status of an asynchronous public operation",
        "security": [],
        "parameters": [
          { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Job status",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatus" } } }
          },
          "404": {
            "description": "Job was not found",
            "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/.well-known/mcp/server-card.json": {
      "get": {
        "operationId": "getMcpServerCard",
        "summary": "Get the MCP server card and tool schemas",
        "security": [],
        "responses": {
          "200": {
            "description": "MCP server card",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryDocument" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/.well-known/agent-card.json": {
      "get": {
        "operationId": "getAgentCard",
        "summary": "Get the A2A agent card",
        "security": [],
        "responses": {
          "200": {
            "description": "A2A agent card",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoveryDocument" } } }
          },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    }
  },
  "components": {
    "headers": {
      "XRateLimitLimit": { "description": "Maximum requests allowed in the current 60-second window", "schema": { "type": "integer", "minimum": 1 } },
      "XRateLimitRemaining": { "description": "Requests remaining in the current window", "schema": { "type": "integer", "minimum": 0 } },
      "XRateLimitReset": { "description": "Unix timestamp when the current window resets", "schema": { "type": "integer", "format": "int64" } }
    },
    "responses": {
      "TooManyRequests": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": { "description": "Seconds until another request can be attempted", "schema": { "type": "integer", "minimum": 1 } },
          "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" },
          "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" },
          "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" }
        },
        "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }
      }
    },
    "schemas": {
      "Status": {
        "type": "object",
        "required": ["status", "service", "time"],
        "properties": {
          "status": { "type": "string", "const": "ok" },
          "service": { "type": "string" },
          "version": { "type": "string" },
          "time": { "type": "string", "format": "date-time" },
          "publicApiAuth": { "type": "string", "const": "none" },
          "mcp": { "type": "string", "format": "uri" }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "method": { "type": "string" },
          "params": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "oneOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] },
          "result": true,
          "error": { "$ref": "#/components/schemas/JsonRpcError" }
        },
        "additionalProperties": true
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["code", "message"],
        "properties": {
          "code": { "type": "integer" },
          "message": { "type": "string" },
          "data": true
        }
      },
      "DiscoveryDocument": { "type": "object", "additionalProperties": true },
      "JobStatus": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["queued", "running", "completed", "failed"] },
          "result": true,
          "error": { "type": "string" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Problem": {
        "type": "object",
        "required": ["title", "status"],
        "properties": {
          "type": { "type": "string", "format": "uri-reference" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" }
        }
      }
    }
  }
}