{
  "openapi": "3.1.0",
  "info": {
    "title": "designpattern.fyi Developer API",
    "version": "1.1.0",
    "description": "Official machine-readable developer API for designpattern.fyi — curated software architecture, Agentic AI, microservices, and design patterns catalog. Enhanced with MCP schema improvements and agent-friendly tool descriptions.",
    "contact": {
      "name": "designpattern.fyi",
      "url": "https://www.designpattern.fyi/developers/"
    },
    "license": {
      "name": "MIT",
      "url": "https://www.designpattern.fyi/LICENSE"
    },
    "x-api-versioning-policy": {
      "versioning": "URL path versioning (/api/v1/, /api/v2/)",
      "current_version": "v1",
      "supported_versions": ["v1"],
      "deprecation_policy": "Deprecation will be announced 6 months in advance via the /developers/ page and Sunset headers. Deprecated versions will be maintained for at least 12 months after deprecation announcement.",
      "migration_guide": "https://www.designpattern.fyi/developers/#versioning"
    }
  },
  "servers": [
    {
      "url": "https://www.designpattern.fyi/api/v1",
      "description": "Production API v1 (Current stable version)"
    },
    {
      "url": "https://www.designpattern.fyi/api",
      "description": "Production API (Latest, redirects to v1)"
    }
  ],
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Structured JSON error response returned for API errors. Canonical example at /api/error.json.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["status", "code", "message"],
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code",
                "example": 404
              },
              "code": {
                "type": "string",
                "description": "Machine-readable error code",
                "example": "RESOURCE_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error description"
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "URL to developer documentation"
              },
              "openapi_spec": {
                "type": "string",
                "format": "uri",
                "description": "URL to this OpenAPI specification"
              }
            }
          },
          "resolution": {
            "type": "object",
            "description": "Recovery hints for agents and API consumers",
            "properties": {
              "description": { "type": "string" },
              "valid_endpoints": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "path": { "type": "string" },
                    "description": { "type": "string" }
                  }
                }
              },
              "discovery": {
                "type": "object",
                "properties": {
                  "sitemap": { "type": "string", "format": "uri" },
                  "llms_txt": { "type": "string", "format": "uri" },
                  "agent_instructions": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Resource not found. Returns structured JSON with error code and resolution hints.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "error": {
                "status": 404,
                "code": "RESOURCE_NOT_FOUND",
                "message": "The requested API resource does not exist on designpattern.fyi.",
                "docs": "https://www.designpattern.fyi/developers/",
                "openapi_spec": "https://www.designpattern.fyi/api/openapi.json"
              }
            }
          }
        },
        "headers": {
          "Content-Type": {
            "schema": { "type": "string" },
            "example": "application/json; charset=utf-8"
          }
        }
      }
    }
  },
  "paths": {
    "/patterns.json": {
      "get": {
        "summary": "Retrieve complete pattern catalog",
        "description": "Returns the complete catalog of 758+ software design patterns with code snippets, pros/cons, and categories. This is the primary JSON feed for AI agents and developers seeking programmatic access to the entire pattern catalog.",
        "operationId": "getPatterns",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Optional category filter to narrow results. Valid values: 'agentic_ai', 'cloud', 'microservices', 'solid', 'owasp_llm', 'owasp_agentic_ai', 'algorithms', 'data_structures', 'event_driven_architecture', 'integration', 'data_science', 'language_models', 'machine_learning'. Use this when you need patterns from a specific domain.",
            "schema": {
              "type": "string",
              "enum": ["agentic_ai", "cloud", "microservices", "solid", "owasp_llm", "owasp_agentic_ai", "algorithms", "data_structures", "event_driven_architecture", "integration", "data_science", "language_models", "machine_learning"]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Optional limit on number of patterns returned (1-758). Use lower values for focused queries or when token budget is constrained. Default returns full catalog.",
            "schema": {
              "type": "integer",
              "default": 758,
              "minimum": 1,
              "maximum": 758
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full pattern catalog JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": { "type": "string", "description": "API version" },
                    "title": { "type": "string", "description": "Catalog title" },
                    "description": { "type": "string", "description": "Catalog description" },
                    "canonical_url": { "type": "string", "format": "uri" },
                    "total_patterns": { "type": "integer", "description": "Total number of patterns" },
                    "patterns": { 
                      "type": "object",
                      "description": "Pattern objects keyed by pattern ID",
                      "additionalProperties": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "category": { "type": "string" },
                          "subtitle": { "type": "string" },
                          "description": { "type": "string" },
                          "use_case": { "type": "string" },
                          "pros": { "type": "array", "items": { "type": "string" } },
                          "cons": { "type": "array", "items": { "type": "string" } },
                          "tldr": { "type": "string" },
                          "source_url": { "type": "string", "format": "uri" }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "version": "1.0.0",
                  "title": "designpattern.fyi Patterns Catalog",
                  "description": "Complete curated catalog of software design patterns and architectural strategies.",
                  "canonical_url": "https://www.designpattern.fyi/",
                  "total_patterns": 758,
                  "patterns": {
                    "circuit_breaker": {
                      "id": "circuit_breaker",
                      "name": "Circuit Breaker",
                      "category": "Microservices",
                      "subtitle": "Prevents cascading failures by failing fast when dependent services are unavailable",
                      "description": "**Intent**: Protect a system from cascading failures when calling external services.\n\n**Context**: Microservices calling external APIs or databases that may be slow or unavailable.\n\n**Solution**: Wrap external calls in a circuit breaker that tracks failures and opens the circuit after a threshold, preventing further calls.",
                      "use_case": "- A microservice calls an external payment API that may be slow or unavailable\n- Use Circuit Breaker to prevent cascading timeouts across your service mesh\n- When the payment API is down, the circuit opens and calls fail fast with a fallback response",
                      "pros": [
                        "Prevents cascading failures across distributed systems",
                        "Provides fast failure when downstream services are unavailable",
                        "Enables graceful degradation with fallback responses"
                      ],
                      "cons": [
                        "Adds complexity to error handling and monitoring",
                        "Requires careful tuning of failure thresholds and timeout values",
                        "May mask underlying issues if not properly monitored"
                      ],
                      "tldr": "Circuit Breaker protects distributed systems from cascading failures by failing fast when dependent services are unavailable.",
                      "source_url": "https://microservices.io/patterns/resilience/circuit-breaker.html"
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/categories.json": {
      "get": {
        "summary": "Retrieve category taxonomies and metadata",
        "description": "Returns all 13 top-level categories and subcategory taxonomies. Use this endpoint to understand the catalog structure and filter patterns by category.",
        "operationId": "getCategories",
        "responses": {
          "200": {
            "description": "Categories metadata JSON",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": { "type": "string", "description": "API version" },
                    "title": { "type": "string", "description": "Categories title" },
                    "total_categories": { "type": "integer", "description": "Total number of categories" },
                    "categories": {
                      "type": "array",
                      "description": "Array of category objects",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "description": "Category ID" },
                          "name": { "type": "string", "description": "Category display name" },
                          "icon": { "type": "string", "description": "Category icon (emoji)" },
                          "type": { "type": "string", "description": "Category type (bucket or section)" },
                          "custom_tagline": { "type": "string", "description": "Category tagline" },
                          "highlights": { "type": "array", "items": { "type": "string" } },
                          "subcategories": {
                            "type": "array",
                            "description": "Subcategory items",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": { "type": "string" },
                                "name": { "type": "string" },
                                "type": { "type": "string" }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "version": "1.0.0",
                  "title": "designpattern.fyi Categories & Taxonomies",
                  "total_categories": 13,
                  "categories": [
                    {
                      "id": "agentic_ai",
                      "name": "Agentic AI",
                      "icon": "🤖",
                      "type": "section",
                      "custom_tagline": "Patterns for autonomous AI agents, cognitive loops, memory architectures, and multi-agent systems.",
                      "highlights": [
                        "Reasoning Patterns",
                        "Memory Patterns",
                        "Planning Patterns"
                      ],
                      "subcategories": [
                        {
                          "id": "reasoning",
                          "name": "Reasoning",
                          "type": "subcategory"
                        },
                        {
                          "id": "memory",
                          "name": "Memory",
                          "type": "subcategory"
                        }
                      ]
                    },
                    {
                      "id": "microservices",
                      "name": "Microservices",
                      "icon": "🔧",
                      "type": "section",
                      "custom_tagline": "Patterns for distributed systems, service communication, and resilience.",
                      "highlights": [
                        "Resilience Patterns",
                        "Communication Patterns",
                        "Data Management"
                      ],
                      "subcategories": [
                        {
                          "id": "resilience",
                          "name": "Resilience",
                          "type": "subcategory"
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/skills.json": {
      "get": {
        "summary": "Retrieve AI agent skills",
        "description": "Returns standardized AI agent skill specifications for autonomous agents. This endpoint provides skill definitions that can be used to package specialized knowledge for AI agents using the Open Knowledge Format (OKF) and Agentic Resource Discovery (ARD) standards.",
        "operationId": "getAgentSkills",
        "responses": {
          "200": {
            "description": "Agent skills JSON feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": { "type": "string", "description": "API version" },
                    "title": { "type": "string", "description": "Skills feed title" },
                    "description": { "type": "string", "description": "Skills feed description" },
                    "skills": {
                      "type": "array",
                      "description": "Array of agent skill specifications",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string", "description": "Skill unique identifier" },
                          "title": { "type": "string", "description": "Skill display title" },
                          "name": { "type": "string", "description": "Skill name" },
                          "icon": { "type": "string", "description": "Skill icon (emoji)" },
                          "file": { "type": "string", "description": "Path to skill definition file" }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "version": "1.0.0",
                  "title": "designpattern.fyi AI Agent Skills Feed",
                  "description": "Curated specification of AI Agent skills and capabilities for autonomous systems.",
                  "skills": [
                    {
                      "id": "document-summarizer",
                      "title": "Document Summarizer",
                      "name": "document-summarizer",
                      "icon": "📄",
                      "file": "/document_summarizer.md"
                    },
                    {
                      "id": "entity-extractor",
                      "title": "Named Entity Extractor",
                      "name": "entity-extractor",
                      "icon": "🔍",
                      "file": "/entity_extractor.md"
                    }
                  ]
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/mcp-schema.json": {
      "get": {
        "summary": "Retrieve Model Context Protocol tool schema",
        "description": "Returns JSON Schema definitions for Claude and Cursor MCP server tool calling.",
        "operationId": "getMcpSchema",
        "responses": {
          "200": {
            "description": "MCP Schema definition",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/error.json": {
      "get": {
        "summary": "Canonical JSON error response schema",
        "description": "Returns the canonical structured JSON error body. Agents and API consumers should consult this when receiving non-200 API responses.",
        "operationId": "getErrorSchema",
        "responses": {
          "200": {
            "description": "Error response schema example",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "summary": "Retrieve LLM guidance index",
        "description": "Plaintext LLM index formatted according to the llms.txt standard.",
        "operationId": "getLlmsTxt",
        "responses": {
          "200": {
            "description": "llms.txt content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/agent-instructions.txt": {
      "get": {
        "summary": "Retrieve Agent Instructions",
        "description": "Plaintext when-to-use guidance and invocation guidelines for autonomous AI agents.",
        "operationId": "getAgentInstructions",
        "responses": {
          "200": {
            "description": "agent-instructions.txt content",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/index.md": {
      "get": {
        "summary": "Retrieve Markdown homepage representation",
        "description": "Token-efficient Markdown homepage according to acceptmarkdown.com standards. Set Accept: text/markdown to receive this via content negotiation.",
        "operationId": "getHomepageMarkdown",
        "parameters": [
          {
            "in": "header",
            "name": "Accept",
            "schema": { "type": "string", "example": "text/markdown" },
            "description": "Set to 'text/markdown' to trigger content negotiation via the Cloudflare Worker middleware."
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown representation",
            "headers": {
              "Vary": {
                "schema": { "type": "string", "example": "Accept, Accept-Encoding" },
                "description": "Vary header ensures CDNs cache HTML and Markdown variants separately."
              },
              "Content-Type": {
                "schema": { "type": "string", "example": "text/markdown; charset=utf-8" }
              }
            },
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}