{
  "openapi": "3.1.0",
  "info": {
    "title": "designmd.app API",
    "description": "Open reference of documented DESIGN.md files for AI coding agents. Browse, search and copy design systems in Markdown format with YAML design tokens.",
    "version": "1.0.0",
    "contact": {
      "name": "designmd.app",
      "email": "contato@ft.ia.br",
      "url": "https://designmd.app"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://designmd.app",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Styles",
      "description": "DESIGN.md library operations"
    },
    {
      "name": "Search",
      "description": "Full-text search operations"
    }
  ],
  "paths": {
    "/api/styles": {
      "get": {
        "operationId": "listStyles",
        "summary": "List DESIGN.md styles",
        "description": "Returns a paginated list of documented DESIGN.md files with metadata. Each item includes title, description, type, cover image, use case, era, style type and keywords.",
        "tags": ["Styles"],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Page number (1-indexed)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page (max 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by style type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["glassmorphism", "neumorphism", "brutalism", "minimalism", "dark-mode", "retro", "futuristic", "organic", "flat", "3d", "gradient", "monochrome"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with paginated styles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StyleSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/styles/{slug}": {
      "get": {
        "operationId": "getStyle",
        "summary": "Get a specific DESIGN.md style",
        "description": "Returns the full DESIGN.md content for a specific style slug, including the complete YAML design tokens and markdown body.",
        "tags": ["Styles"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Style slug (e.g., glassmorphism, neumorphism)",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with full style data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StyleDetail"
                }
              }
            }
          },
          "404": {
            "description": "Style not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/styles/{slug}/token": {
      "get": {
        "operationId": "getStyleToken",
        "summary": "Get design tokens for a style",
        "description": "Returns only the YAML design tokens (colors, typography, spacing, etc.) for a specific style, without the markdown body.",
        "tags": ["Styles"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Style slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with design tokens",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DesignTokens"
                }
              }
            }
          },
          "404": {
            "description": "Style not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/styles/{slug}/content": {
      "get": {
        "operationId": "getStyleContent",
        "summary": "Get markdown content for a style",
        "description": "Returns only the markdown body (design rationale prose) for a specific style, without the YAML tokens.",
        "tags": ["Styles"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "description": "Style slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with markdown content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarkdownContent"
                }
              }
            }
          },
          "404": {
            "description": "Style not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchStyles",
        "summary": "Search DESIGN.md styles",
        "description": "Full-text search across all DESIGN.md files by name, description, keywords, era, or style type. Uses SQLite FTS5 for relevance-ranked results.",
        "tags": ["Search"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query (minimum 2 characters)",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (1-indexed)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page (max 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/StyleSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query (too short)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "StyleSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "Unique identifier"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly identifier"
          },
          "title": {
            "type": "string",
            "description": "Display name"
          },
          "description": {
            "type": "string",
            "description": "Short description"
          },
          "type": {
            "type": "string",
            "description": "Style category"
          },
          "cover": {
            "type": "string",
            "description": "Cover image URL",
            "nullable": true
          },
          "use_case": {
            "type": "string",
            "description": "Recommended use case",
            "nullable": true
          },
          "era": {
            "type": "string",
            "description": "Design era (e.g., 2020s)",
            "nullable": true
          },
          "style_type": {
            "type": "string",
            "description": "Style type classification",
            "nullable": true
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Search keywords"
          },
          "synced_at": {
            "type": "string",
            "format": "date-time",
            "description": "Last sync timestamp"
          }
        },
        "required": ["id", "slug", "title", "description", "type"]
      },
      "StyleDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StyleSummary"
          },
          {
            "type": "object",
            "properties": {
              "designmd": {
                "type": "string",
                "description": "Complete DESIGN.md content with YAML front matter"
              },
              "whenToUse": {
                "type": "string",
                "description": "When to use this style",
                "nullable": true
              },
              "historicalContext": {
                "type": "string",
                "description": "Historical context and background",
                "nullable": true
              }
            },
            "required": ["designmd"]
          }
        ]
      },
      "DesignTokens": {
        "type": "object",
        "description": "YAML design tokens extracted from DESIGN.md",
        "properties": {
          "colors": {
            "type": "object",
            "description": "Color tokens"
          },
          "typography": {
            "type": "object",
            "description": "Typography tokens"
          },
          "spacing": {
            "type": "object",
            "description": "Spacing tokens"
          },
          "rounded": {
            "type": "object",
            "description": "Border radius tokens"
          },
          "components": {
            "type": "object",
            "description": "Component tokens"
          }
        }
      },
      "MarkdownContent": {
        "type": "object",
        "description": "Markdown body content",
        "properties": {
          "content": {
            "type": "string",
            "description": "Markdown-formatted design rationale"
          }
        },
        "required": ["content"]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Items per page"
          },
          "total": {
            "type": "integer",
            "description": "Total items available"
          },
          "totalPages": {
            "type": "integer",
            "description": "Total number of pages"
          }
        },
        "required": ["page", "limit", "total", "totalPages"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "code": {
            "type": "string",
            "description": "Error code",
            "nullable": true
          },
          "details": {
            "type": "string",
            "description": "Additional error details",
            "nullable": true
          }
        },
        "required": ["error"]
      }
    }
  },
  "externalDocs": {
    "description": "Full documentation",
    "url": "https://designmd.app/developers"
  }
}