{
  "openapi": "3.1.0",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "AIOD Agent Discovery API",
    "summary": "Public discovery endpoints for AIOD's agent and MCP integration.",
    "description": "Versioned, unauthenticated metadata for discovering AIOD's agent capabilities. Store-specific discount actions use the OAuth-protected AIOD MCP server linked by this API. Breaking REST changes use a new major URL path.",
    "version": "1.0.0",
    "contact": {
      "name": "AIOD support",
      "url": "https://www.aiodapp.com/contact/",
      "email": "aiod-app@dtcdevelopers.org"
    }
  },
  "servers": [
    {
      "url": "https://www.aiodapp.com",
      "description": "AIOD production website and public discovery API"
    }
  ],
  "externalDocs": {
    "description": "AIOD developer and agent documentation",
    "url": "https://www.aiodapp.com/developers/"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Public, unauthenticated service and agent capability metadata."
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "operationId": "getAiodApiHealth",
        "summary": "Check the AIOD public API",
        "description": "Returns a small health document so agents can verify that AIOD's public discovery API is reachable.",
        "tags": ["Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "The public discovery API is available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "examples": {
                  "healthy": {
                    "value": {
                      "status": "ok",
                      "service": "AIOD public API",
                      "apiVersion": "v1",
                      "documentation": "https://www.aiodapp.com/developers/",
                      "openapi": "https://www.aiodapp.com/openapi.json",
                      "capabilities": "https://www.aiodapp.com/api/v1/agent-capabilities"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/agent-capabilities": {
      "get": {
        "operationId": "getAiodAgentCapabilities",
        "summary": "Discover AIOD agent capabilities",
        "description": "Returns the MCP server address, OAuth discovery documents, supported protocol revisions, tool documentation, capabilities, and safety limits.",
        "tags": ["Discovery"],
        "security": [],
        "responses": {
          "200": {
            "description": "AIOD agent and MCP discovery metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCapabilitiesResponse"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["status", "service", "apiVersion", "documentation", "openapi", "capabilities"],
        "properties": {
          "status": {
            "type": "string",
            "const": "ok",
            "description": "Current service status."
          },
          "service": {
            "type": "string",
            "description": "Human-readable service name."
          },
          "apiVersion": {
            "type": "string",
            "const": "v1",
            "description": "Stable major version of the REST discovery API."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Canonical MCP documentation URL."
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "description": "Canonical OpenAPI document URL."
          },
          "capabilities": {
            "type": "string",
            "format": "uri",
            "description": "Versioned agent capability endpoint URL."
          }
        }
      },
      "AgentCapabilitiesResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "description", "apiVersion", "public", "openapi", "documentation", "discovery", "rest", "mcp"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Unambiguous AIOD product name."
          },
          "description": {
            "type": "string",
            "description": "What agents can do through AIOD."
          },
          "apiVersion": {
            "type": "string",
            "description": "Version of this discovery response."
          },
          "public": {
            "type": "boolean",
            "description": "Whether this discovery resource requires authentication."
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "description": "OpenAPI document for the public discovery API."
          },
          "documentation": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable developer and agent documentation."
          },
          "discovery": {
            "$ref": "#/components/schemas/DiscoveryResources"
          },
          "rest": {
            "$ref": "#/components/schemas/RestDiscoveryService"
          },
          "mcp": {
            "$ref": "#/components/schemas/McpService"
          }
        }
      },
      "DiscoveryResources": {
        "type": "object",
        "additionalProperties": false,
        "required": ["apiCatalog", "ard", "agentSkills", "agentPlugin", "mcpManifest"],
        "properties": {
          "apiCatalog": {
            "type": "string",
            "format": "uri",
            "description": "RFC 9727 API catalog for AIOD's REST and MCP surfaces."
          },
          "ard": {
            "type": "string",
            "format": "uri",
            "description": "Agentic Resource Discovery manifest."
          },
          "agentSkills": {
            "type": "string",
            "format": "uri",
            "description": "Index of reusable AIOD agent skills."
          },
          "agentPlugin": {
            "type": "string",
            "format": "uri",
            "description": "Agent Plugins manifest for AIOD's MCP server and skill."
          },
          "mcpManifest": {
            "type": "string",
            "format": "uri",
            "description": "Standard MCP manifest for compatible clients and readiness scanners."
          }
        }
      },
      "RestDiscoveryService": {
        "type": "object",
        "additionalProperties": false,
        "required": ["baseUrl", "version", "authentication", "health", "capabilities", "deprecationPolicy"],
        "properties": {
          "baseUrl": {
            "type": "string",
            "format": "uri",
            "description": "Base URL for the stable REST discovery version."
          },
          "version": {
            "type": "string",
            "const": "v1",
            "description": "Current stable major version."
          },
          "authentication": {
            "type": "string",
            "const": "none",
            "description": "Authentication required for public discovery endpoints."
          },
          "health": {
            "type": "string",
            "format": "uri",
            "description": "Versioned health endpoint."
          },
          "capabilities": {
            "type": "string",
            "format": "uri",
            "description": "Versioned agent capability endpoint."
          },
          "deprecationPolicy": {
            "type": "string",
            "format": "uri",
            "description": "Versioning, Deprecation header, and Sunset header policy."
          }
        }
      },
      "McpService": {
        "type": "object",
        "additionalProperties": false,
        "required": ["server", "transport", "stateless", "method", "authentication", "scope", "protocolVersions", "manifest", "serverCard", "protectedResourceMetadata", "authorizationServerMetadata", "toolReference", "capabilities", "safety"],
        "properties": {
          "server": {
            "type": "string",
            "format": "uri",
            "description": "AIOD's production MCP endpoint."
          },
          "transport": {
            "type": "string",
            "enum": ["streamable-http"],
            "description": "MCP transport supported by the server."
          },
          "stateless": {
            "type": "boolean",
            "description": "Whether the server keeps an HTTP session between requests."
          },
          "method": {
            "type": "string",
            "enum": ["POST"],
            "description": "HTTP method accepted by the MCP endpoint."
          },
          "authentication": {
            "type": "string",
            "description": "Authentication flow required for store-specific tools."
          },
          "scope": {
            "type": "string",
            "const": "aiod:discounts",
            "description": "OAuth scope requested by the MCP server."
          },
          "protocolVersions": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"
            },
            "description": "Supported MCP protocol revisions."
          },
          "manifest": {
            "type": "string",
            "format": "uri",
            "description": "Standard MCP manifest exposing the Streamable HTTP server configuration."
          },
          "serverCard": {
            "type": "string",
            "format": "uri",
            "description": "Experimental MCP Server Card for pre-connection discovery."
          },
          "protectedResourceMetadata": {
            "type": "string",
            "format": "uri",
            "description": "OAuth protected resource metadata document."
          },
          "authorizationServerMetadata": {
            "type": "string",
            "format": "uri",
            "description": "OAuth authorization server metadata document."
          },
          "toolReference": {
            "type": "string",
            "format": "uri",
            "description": "Typed parameter and response documentation for every MCP tool."
          },
          "capabilities": {
            "type": "array",
            "items": { "type": "string" },
            "description": "High-level actions exposed through MCP."
          },
          "safety": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Important limits on write behavior and store access."
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "additionalProperties": false,
        "required": ["type", "title", "status", "detail", "instance", "code", "resolution"],
        "properties": {
          "type": { "type": "string", "format": "uri-reference", "description": "URI identifying the problem type." },
          "title": { "type": "string", "description": "Short, stable problem summary." },
          "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status code." },
          "detail": { "type": "string", "description": "Problem detail for this occurrence." },
          "instance": { "type": "string", "format": "uri-reference", "description": "URI identifying this occurrence." },
          "code": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]+$", "description": "Stable machine-readable AIOD error code." },
          "resolution": { "type": "string", "description": "Action an agent can take to resolve the problem." },
          "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" }, "description": "Related recovery links." }
        }
      }
    },
    "responses": {
      "ApiError": {
        "description": "A structured API error using RFC 9457 Problem Details fields plus AIOD recovery hints.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "AiodOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code flow with PKCE (S256) for the AIOD MCP server. Public REST discovery endpoints do not require this scope.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://aiod-automatic-discount.com/oauth/authorize",
            "tokenUrl": "https://aiod-automatic-discount.com/oauth/token",
            "scopes": {
              "aiod:discounts": "Read, draft, test, and report on AIOD discounts for the authorized Shopify store."
            }
          }
        },
        "x-authorization-server-metadata": "https://aiod-automatic-discount.com/.well-known/oauth-authorization-server",
        "x-protected-resource-metadata": "https://aiod-automatic-discount.com/.well-known/oauth-protected-resource"
      }
    }
  },
  "x-api-versioning": {
    "strategy": "URL path major versioning",
    "currentVersion": "v1",
    "breakingChanges": "Breaking REST contract changes use a new /api/v{major}/ path.",
    "deprecation": "Scheduled deprecations use the RFC 9745 Deprecation header. A Sunset header is added only after a retirement date is set.",
    "policy": "https://www.aiodapp.com/developers/#versioning-and-deprecation"
  },
  "x-mcp-server": {
    "url": "https://aiod-automatic-discount.com/mcp",
    "transport": "streamable-http",
    "authentication": "OAuth 2.1 with PKCE (S256)",
    "scope": "aiod:discounts",
    "manifest": "https://www.aiodapp.com/.well-known/mcp.json",
    "serverCard": "https://www.aiodapp.com/.well-known/mcp/server-card.json",
    "protectedResourceMetadata": "https://aiod-automatic-discount.com/.well-known/oauth-protected-resource",
    "authorizationServerMetadata": "https://aiod-automatic-discount.com/.well-known/oauth-authorization-server",
    "security": [
      {
        "AiodOAuth": ["aiod:discounts"]
      }
    ],
    "documentation": "https://www.aiodapp.com/docs/mcp-server/tools"
  }
}