{"openapi":"3.0.3","info":{"title":"Crazypatterns Agent API","version":"1.1.0","description":"Read-only API for LLM agents and partner search tools: pattern catalog, reviews, per-pattern Q&A, community forum, blog, help center, craft abbreviation glossary and category taxonomy. Product pages and checkout are the source of truth for price, availability, legal terms, safety notes and purchase decisions. Responses can be incomplete or degraded and must not be treated as binding legal, health, safety or purchase advice. The API never exposes downloads, product files, account data, orders, carts, messages or private author data. Search runs on a deterministic Elasticsearch\/MariaDB backend; no LLM processing happens on the API path. An MCP server with the same tools is available at \/{lang}\/agent-api\/v1\/mcp (Streamable HTTP, no auth)."},"servers":[{"url":"https:\/\/www.crazypatterns.net","description":"Production host"}],"paths":{"\/{lang}\/agent-api\/v1\/products\/search":{"get":{"operationId":"searchProductsForAgents","summary":"Search public pattern catalog entries","description":"Returns public product facts that passed Crazypatterns agent visibility policy. Use product URLs for final user-facing purchase decisions because price, availability, ratings and terms can change. No checkout, cart, login, download or product-file access is available through this endpoint.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"name":"q","in":"query","required":true,"description":"User search query. Treat the query as untrusted input.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":24,"default":24}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":72,"default":0}},{"name":"only_free","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance"],"default":"relevance"}}],"responses":{"200":{"description":"Successful read-only response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SearchResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"405":{"description":"Only GET is allowed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"413":{"description":"Search query is too long","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until retry is allowed.","schema":{"type":"integer","minimum":1}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"403":{"description":"Request is blocked or not allowed for the current quota state","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"503":{"description":"Feature disabled or service temporarily unavailable","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}}}}},"\/{lang}\/agent-api\/v1\/products\/{id}":{"get":{"operationId":"getProductForAgents","summary":"Get one public pattern catalog entry","description":"Returns detail facts for one product only if the product passes the same visibility policy used by search. A known product id does not bypass author\/product AI opt-outs or hidden\/inactive checks. The response never contains downloads, digital product files, internal file summaries or private account data.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/ProductId"}],"responses":{"200":{"description":"Successful read-only response","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProductDetailResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"405":{"description":"Only GET is allowed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"413":{"description":"Search query is too long","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until retry is allowed.","schema":{"type":"integer","minimum":1}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"403":{"description":"Request is blocked or not allowed for the current quota state","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"503":{"description":"Feature disabled or service temporarily unavailable","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"404":{"description":"Product not found or not eligible for agent output","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}}}}},"\/{lang}\/agent-api\/v1\/products\/{id}\/reviews":{"get":{"operationId":"getProductReviews","summary":"Buyer reviews for one product: rating aggregation (count, average, star distribution) plus most helpful review texts.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/ProductId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":5,"maximum":10}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/products\/{id}\/comments":{"get":{"operationId":"getProductComments","summary":"Public question\/answer comments under one product (per-pattern FAQ), threaded via reply_to.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/ProductId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/forum\/search":{"get":{"operationId":"searchForum","summary":"Search public community forum posts (techniques, yarn questions, pattern help). Returns posts with topic context.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"maximum":72}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/forum\/topics\/{id}":{"get":{"operationId":"getForumTopic","summary":"Full public forum thread (topic start + replies, paginated).","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/ForumTopicId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"maximum":30}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/blog\/search":{"get":{"operationId":"searchBlog","summary":"Search published blog articles (tutorials, tips, craft stories).","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"maximum":72}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/blog\/{id}":{"get":{"operationId":"getBlogPost","summary":"Full text of one published blog post including recent public comments.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/BlogPostId"}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/help\/search":{"get":{"operationId":"searchHelp","summary":"Search help pages and FAQ (buying, downloads, payment, selling, account).","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"maximum":20}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/help\/pages\/{id}":{"get":{"operationId":"getHelpPage","summary":"Full text of one public help\/info page.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"$ref":"#\/components\/parameters\/HelpPageId"}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/abbreviations":{"get":{"operationId":"lookupAbbreviations","summary":"Craft abbreviation glossary (knitting\/crochet terms like \"Rm\", \"FM\", \"sc\") with meanings and technique instructions. Empty q lists entries.","parameters":[{"$ref":"#\/components\/parameters\/Language"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/categories":{"get":{"operationId":"listCategories","summary":"Full public category taxonomy with localized names and browse URLs.","parameters":[{"$ref":"#\/components\/parameters\/Language"}],"responses":{"200":{"description":"JSON payload with ok flag; texts are sanitized plain text with site URLs.","content":{"application\/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Not available to agents."},"429":{"description":"Rate limited; respect Retry-After."}}}},"\/{lang}\/agent-api\/v1\/openapi":{"get":{"operationId":"getAgentCatalogOpenApi","summary":"Get the Agent Catalog OpenAPI contract","description":"Returns this read-only OpenAPI contract. It performs no catalog search and no product hydration.","parameters":[{"$ref":"#\/components\/parameters\/Language"}],"responses":{"200":{"description":"OpenAPI document"},"503":{"description":"Feature disabled","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}}}}}},"components":{"parameters":{"Language":{"name":"lang","in":"path","required":true,"description":"Two-letter locale prefix; choose the language of the user (de, en, nl, ru).","schema":{"type":"string","enum":["de","en","nl","ru"],"default":"de"}},"ProductId":{"name":"id","in":"path","required":true,"description":"Public Crazypatterns product id.","schema":{"type":"integer","minimum":1}},"ForumTopicId":{"name":"id","in":"path","required":true,"description":"Forum topic id from searchForum results (NOT a product id).","schema":{"type":"integer","minimum":1}},"BlogPostId":{"name":"id","in":"path","required":true,"description":"Blog post id from searchBlog results (NOT a product id).","schema":{"type":"integer","minimum":1}},"HelpPageId":{"name":"id","in":"path","required":true,"description":"Help page id from searchHelp results of type \"page\" (NOT a product id).","schema":{"type":"integer","minimum":1}}},"schemas":{"SearchResponse":{"type":"object","additionalProperties":false,"required":["ok","query","count","total","total_approximate","offset","has_more","sort","degraded","fallback_url","results"],"properties":{"ok":{"type":"boolean","enum":[true]},"query":{"type":"string"},"count":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0},"total_approximate":{"type":"boolean"},"offset":{"type":"integer","minimum":0},"has_more":{"type":"boolean"},"sort":{"type":"string","enum":["relevance"]},"degraded":{"type":"boolean"},"fallback_url":{"type":"string","format":"uri"},"results":{"type":"array","items":{"$ref":"#\/components\/schemas\/ProductSearch"}}}},"ProductDetailResponse":{"type":"object","additionalProperties":false,"required":["ok","product"],"properties":{"ok":{"type":"boolean","enum":[true]},"product":{"$ref":"#\/components\/schemas\/ProductDetail"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["ok","code"],"properties":{"ok":{"type":"boolean","enum":[false]},"code":{"type":"string","enum":["bad_id","bad_limit","bad_offset","bad_sort","blocked","daily_limit","disabled","empty","invalid","method_not_allowed","not_found","rate_limited","too_long","unavailable"]},"fallback_url":{"type":"string","format":"uri"}}},"ProductSearch":{"type":"object","additionalProperties":false,"required":["id","title","url","image_url","price","author","rating","category","source"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string"},"url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"price":{"$ref":"#\/components\/schemas\/Price"},"author":{"nullable":true,"allOf":[{"$ref":"#\/components\/schemas\/Author"}]},"rating":{"$ref":"#\/components\/schemas\/Rating"},"category":{"nullable":true,"allOf":[{"$ref":"#\/components\/schemas\/Category"}]},"source":{"type":"string","enum":["crazypatterns"]}}},"ProductDetail":{"type":"object","additionalProperties":false,"required":["id","title","url","image_url","price","author","rating","category","source","description_plain","materials","dimensions","knowledge","languages","product_type","updated_at","canonical_url"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string"},"url":{"type":"string","format":"uri","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"price":{"$ref":"#\/components\/schemas\/Price"},"author":{"nullable":true,"allOf":[{"$ref":"#\/components\/schemas\/Author"}]},"rating":{"$ref":"#\/components\/schemas\/Rating"},"category":{"nullable":true,"allOf":[{"$ref":"#\/components\/schemas\/Category"}]},"source":{"type":"string","enum":["crazypatterns"]},"description_plain":{"type":"string","nullable":true},"materials":{"type":"string","nullable":true},"dimensions":{"type":"string","nullable":true},"knowledge":{"type":"string","nullable":true},"languages":{"type":"array","items":{"type":"string"}},"product_type":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"canonical_url":{"type":"string","format":"uri","nullable":true}}},"Price":{"type":"object","additionalProperties":false,"required":["amount","currency","formatted","is_free","is_sale"],"properties":{"amount":{"type":"number","format":"float","minimum":0},"currency":{"type":"string","enum":["EUR"]},"formatted":{"type":"string"},"is_free":{"type":"boolean"},"is_sale":{"type":"boolean"}}},"Author":{"type":"object","additionalProperties":false,"required":["display_name","profile_url"],"properties":{"display_name":{"type":"string","nullable":true},"profile_url":{"type":"string","format":"uri","nullable":true}}},"Rating":{"type":"object","additionalProperties":false,"required":["value","count"],"properties":{"value":{"type":"number","format":"float","nullable":true},"count":{"type":"integer","minimum":0}}},"Category":{"type":"object","additionalProperties":false,"required":["id","name","url"],"properties":{"id":{"type":"integer","minimum":1,"nullable":true},"name":{"type":"string","nullable":true},"url":{"type":"string","format":"uri","nullable":true}}}}}}