{"openapi":"3.1.0","info":{"title":"Brand Peel API","version":"1.0.0","description":"Public API and agent integration endpoints for Brand Peel — the local-first desktop AI brand strategist and design token compiler.","termsOfService":"https://brandpeel.app/legal/imprint","contact":{"name":"Brand Peel Support","url":"https://brandpeel.app/contact","email":"support@brandpeel.app"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"x-api-deprecation-policy":{"versioningScheme":"URL path (/api/v1/)","deprecationNotice":"Deprecated endpoints will return a Deprecation: true header and a Sunset header with the removal date at least 90 days in advance.","currentVersion":"1.0.0","sunsetPolicy":"https://brandpeel.app/developers#api-versioning"},"servers":[{"url":"https://brandpeel.app","description":"Brand Peel Production Server"}],"paths":{"/api/v1/health":{"get":{"operationId":"getHealthStatus","summary":"Check API and agent service health","description":"Returns operational status, version, and links to machine-readable agent discovery documents.","responses":{"200":{"description":"Service is operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/release/latest":{"get":{"operationId":"getLatestReleaseDownload","summary":"Retrieve latest desktop release downloads and checksums","description":"Provides download URLs for Windows (setup/portable x64), macOS (universal/arm64/x64 DMG), and Linux (AppImage/portable).","parameters":[{"name":"platform","in":"query","required":false,"description":"Filter by operating system platform.","schema":{"type":"string","enum":["windows","macos","linux"]}},{"name":"channel","in":"query","required":false,"description":"Release channel to fetch.","schema":{"type":"string","enum":["stable","alpha","beta"],"default":"alpha"}}],"responses":{"200":{"description":"Release downloads payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/tools":{"get":{"operationId":"listBrandTools","summary":"List or search free branding and design tools","description":"Returns the catalog of free utilities for color generation, typography, contrast calculation, and token export.","parameters":[{"name":"category","in":"query","required":false,"description":"Filter tools by category name.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search query for keywords or tool names.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of matching tools and categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolListResponse"}}}}}}},"/api/v1/tools/{slug}":{"get":{"operationId":"getBrandToolBySlug","summary":"Retrieve single brand tool specification","description":"Returns metadata, outcome description, URL, and keywords for an individual tool.","parameters":[{"name":"slug","in":"path","required":true,"description":"The unique slug identifier of the tool.","schema":{"type":"string"}}],"responses":{"200":{"description":"Tool details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDetail"}}}},"404":{"description":"Tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/brand-guide/schema":{"get":{"operationId":"getBrandGuideSchema","summary":"Retrieve Brand Peel export JSON Schema","description":"Returns the standard schema for brand books, design tokens, color models (OKLCH/HSL/Hex), and Tailwind v4 configurations.","responses":{"200":{"description":"JSON Schema document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandGuideSchemaResponse"}}}}}}},"/api/v1/agent-info":{"get":{"operationId":"getAgentCapabilities","summary":"Get agent integration capabilities and when-to-use guidance","description":"Returns machine-readable information on when and how AI agents should utilize Brand Peel.","responses":{"200":{"description":"Agent capabilities and guidance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInfoResponse"}}}}}}},"/api/v1/cli/manifest":{"get":{"operationId":"getCliManifest","summary":"Get Brand Peel CLI tool manifest","description":"Provides command options and package specifications for scripting brand token operations.","responses":{"200":{"description":"CLI tool manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CliManifestResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error","statusCode","message"],"properties":{"error":{"type":"string","example":"NOT_FOUND"},"statusCode":{"type":"integer","example":404},"message":{"type":"string","example":"The requested resource was not found."},"resolutionHints":{"type":"array","items":{"type":"string"},"example":["Check URL for typos","Inspect https://brandpeel.app/openapi.json"]},"documentationUrl":{"type":"string","example":"https://brandpeel.app/developers"}}},"HealthResponse":{"type":"object","required":["status","service","version","timestamp"],"properties":{"status":{"type":"string","example":"healthy"},"service":{"type":"string","example":"Brand Peel Public API"},"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","format":"date-time"},"agentReadiness":{"type":"object","properties":{"openApiSpec":{"type":"string","format":"uri","example":"https://brandpeel.app/openapi.json"},"llmsSummary":{"type":"string","format":"uri","example":"https://brandpeel.app/llms.txt"},"llmsFull":{"type":"string","format":"uri","example":"https://brandpeel.app/llms-full.txt"},"agentInstructions":{"type":"string","format":"uri","example":"https://brandpeel.app/agent-instructions.md"},"developerPortal":{"type":"string","format":"uri","example":"https://brandpeel.app/developers"},"acceptMarkdownCompliant":{"type":"boolean","example":true}}}}},"ReleaseResponse":{"type":"object","required":["version","channel"],"properties":{"version":{"type":"string","example":"0.1.0-alpha"},"channel":{"type":"string","enum":["stable","alpha","beta"],"example":"alpha"},"platforms":{"type":"object","properties":{"windows":{"type":"object","properties":{"x64":{"type":"object","properties":{"setup":{"type":"string","format":"uri"},"portable":{"type":"string","format":"uri"}}}}},"macos":{"type":"object","properties":{"universal":{"type":"object","properties":{"dmg":{"type":"string","format":"uri"}}},"arm64":{"type":"object","properties":{"dmg":{"type":"string","format":"uri"}}},"x64":{"type":"object","properties":{"dmg":{"type":"string","format":"uri"}}}}},"linux":{"type":"object","properties":{"x64":{"type":"object","properties":{"appimage":{"type":"string","format":"uri"},"portable":{"type":"string","format":"uri"}}},"arm64":{"type":"object","properties":{"portable":{"type":"string","format":"uri"}}}}}}},"documentation":{"type":"string","format":"uri"},"downloadsPage":{"type":"string","format":"uri"}}},"ToolDetail":{"type":"object","required":["id","name","summary","category","outcome","url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"category":{"type":"string"},"outcome":{"type":"string"},"url":{"type":"string"},"path":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}}}},"ToolListResponse":{"type":"object","required":["total","tools","categories"],"properties":{"total":{"type":"integer"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDetail"}},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"}}}}}},"AgentInfoResponse":{"type":"object","required":["name","description","homepage","whenToUse","functions"],"properties":{"name":{"type":"string","example":"Brand Peel"},"description":{"type":"string"},"homepage":{"type":"string","format":"uri"},"developerPortal":{"type":"string","format":"uri"},"openApiSpec":{"type":"string","format":"uri"},"whenToUse":{"type":"array","items":{"type":"string"}},"whenNotToUse":{"type":"array","items":{"type":"string"}},"functions":{"type":"array","items":{"type":"object","required":["name","description","parameters"],"properties":{"name":{"type":"string","description":"Unique function name matching an OpenAPI operationId."},"description":{"type":"string","description":"Human-readable description of what the function does."},"parameters":{"type":"object","description":"JSON Schema object describing accepted parameters.","properties":{"type":{"type":"string","enum":["object"]},"properties":{"type":"object"}}}}}}}},"CliManifestResponse":{"type":"object","required":["package","version","commands"],"properties":{"package":{"type":"string","example":"brandpeel"},"npmUrl":{"type":"string","format":"uri","example":"https://www.npmjs.com/package/brandpeel"},"install":{"type":"object","properties":{"global":{"type":"string","example":"npm install -g brandpeel"},"npx":{"type":"string","example":"npx brandpeel"},"pnpm":{"type":"string","example":"pnpm dlx brandpeel"}}},"version":{"type":"string","example":"0.1.0"},"description":{"type":"string"},"commands":{"type":"array","items":{"type":"object","required":["command","summary"],"properties":{"command":{"type":"string","description":"CLI command syntax."},"summary":{"type":"string","description":"What the command does."},"options":{"type":"array","items":{"type":"object","required":["flag","description"],"properties":{"flag":{"type":"string"},"description":{"type":"string"}}}}}}}}},"BrandGuideSchemaResponse":{"type":"object","required":["$schema","$id","title","description","type","required","properties"],"properties":{"$schema":{"type":"string","example":"https://json-schema.org/draft/2020-12/schema"},"$id":{"type":"string","example":"https://brandpeel.app/api/v1/brand-guide/schema"},"title":{"type":"string","example":"BrandPeelBrandPackage"},"description":{"type":"string"},"type":{"type":"string","example":"object"},"required":{"type":"array","items":{"type":"string"}},"properties":{"type":"object","properties":{"version":{"type":"object"},"brand":{"type":"object"},"strategy":{"type":"object"},"tokens":{"type":"object"},"exports":{"type":"object"}}}}}}}}