{"openapi":"3.1.0","info":{"title":"Toggle Public API","version":"1.0.0","description":"Stable read-only catalog and prompt-token recommendation API for external clients and agents."},"externalDocs":{"description":"Toggle developer and agent integration guide","url":"/developers"},"x-mcp-endpoint":"/mcp","servers":[{"url":"/"}],"tags":[{"name":"Catalog"},{"name":"Search"},{"name":"Prompt"}],"paths":{"/api/v1/categories":{"get":{"operationId":"listCategories","tags":["Catalog"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"parentId","in":"query","schema":{"type":["string","null"]}}],"responses":{"200":{"description":"Category page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCategoryListResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"409":{"description":"Catalog revision changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/api/v1/categories/{categoryId}":{"get":{"operationId":"getCategory","tags":["Catalog"],"parameters":[{"name":"categoryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Category detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCategoryDetailResponse"}}}},"404":{"description":"Category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/api/v1/tokens":{"get":{"operationId":"listTokens","tags":["Catalog"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"categoryId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Token page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTokenListResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"409":{"description":"Catalog revision changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/api/v1/tokens/{tokenId}":{"get":{"operationId":"getToken","tags":["Catalog"],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTokenDetailResponse"}}}},"404":{"description":"Token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/api/v1/search":{"post":{"operationId":"searchTokens","tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTokenSearchRequest"}}}},"responses":{"200":{"description":"Ranked token results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicTokenSearchResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/api/v1/prompt/recommend":{"post":{"operationId":"recommendPromptTokens","tags":["Prompt"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPromptRecommendationRequest"}}}},"responses":{"200":{"description":"Ranked recommendations for a prompt fragment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPromptRecommendationResponse"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}}},"components":{"schemas":{"PublicApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"details":{}},"required":["error"],"additionalProperties":false},"PublicCategoryDetailResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"catalogRevision":{"type":"string"},"category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"nameEn":{"type":"string"},"searchAliases":{"type":"array","items":{"type":"string"}},"parentId":{"type":"string"},"iconUrl":{"type":"string"},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false}},"required":["id","name","searchAliases","links"],"additionalProperties":false}},"required":["apiVersion","catalogRevision","category"],"additionalProperties":false},"PublicCategoryListResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"nameEn":{"type":"string"},"searchAliases":{"type":"array","items":{"type":"string"}},"parentId":{"type":"string"},"iconUrl":{"type":"string"},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false}},"required":["id","name","searchAliases","links"],"additionalProperties":false}},"page":{"type":"object","properties":{"catalogRevision":{"type":"string"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["catalogRevision","nextCursor"],"additionalProperties":false}},"required":["apiVersion","items","page"],"additionalProperties":false},"PublicTokenListResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"wordForms":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"exampleCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"coverImageUrl":{"type":"string"},"previewImageUrls":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false}},"required":["id","name","description","aliases","wordForms","categoryIds","exampleCount","previewImageUrls","links"],"additionalProperties":false}},"page":{"type":"object","properties":{"catalogRevision":{"type":"string"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["catalogRevision","nextCursor"],"additionalProperties":false}},"required":["apiVersion","items","page"],"additionalProperties":false},"PublicTokenDetailResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"catalogRevision":{"type":"string"},"token":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"wordForms":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false},"examples":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"ordinal":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"image"},"url":{"type":"string"}},"required":["ordinal","kind","url"],"additionalProperties":false},{"type":"object","properties":{"ordinal":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","const":"text"},"text":{"type":"string"}},"required":["ordinal","kind","text"],"additionalProperties":false}]}},"synonymGroupId":{"type":"string"}},"required":["id","name","description","aliases","wordForms","categoryIds","links","examples"],"additionalProperties":false}},"required":["apiVersion","catalogRevision","token"],"additionalProperties":false},"PublicTokenSearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":240},"mode":{"default":"hybrid","type":"string","enum":["lexical","hybrid"]},"limit":{"default":10,"type":"integer","minimum":1,"maximum":10},"fields":{"default":{"names":true,"aliases":true,"wordForms":true,"descriptions":true,"categories":true},"type":"object","properties":{"names":{"default":true,"type":"boolean"},"aliases":{"default":true,"type":"boolean"},"wordForms":{"default":true,"type":"boolean"},"descriptions":{"default":true,"type":"boolean"},"categories":{"default":true,"type":"boolean"}},"required":["names","aliases","wordForms","descriptions","categories"],"additionalProperties":false},"scope":{"default":{"activeCategoryId":null,"requiredFilterCategoryIds":[]},"type":"object","properties":{"activeCategoryId":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"requiredFilterCategoryIds":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["activeCategoryId","requiredFilterCategoryIds"],"additionalProperties":false}},"required":["query","mode","limit","fields","scope"],"additionalProperties":false},"PublicTokenSearchResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"query":{"type":"string"},"catalogRevision":{"type":"string"},"mode":{"type":"string","enum":["lexical","hybrid"]},"state":{"type":"string","enum":["ready","lexical-fallback"]},"fallbackReason":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["lexical","semantic","hybrid"]},"matchedFields":{"type":"array","items":{"type":"string","enum":["name","alias","wordForm","description","category"]}},"matchedTerms":{"type":"array","items":{"type":"string"}},"token":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"wordForms":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"exampleCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"coverImageUrl":{"type":"string"},"previewImageUrls":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false}},"required":["id","name","description","aliases","wordForms","categoryIds","exampleCount","previewImageUrls","links"],"additionalProperties":false}},"required":["rank","source","matchedFields","matchedTerms","token"],"additionalProperties":false}}},"required":["apiVersion","query","catalogRevision","mode","state","results"],"additionalProperties":false},"PublicPromptRecommendationRequest":{"type":"object","properties":{"fragment":{"type":"string","minLength":1,"maxLength":240},"limit":{"default":10,"type":"integer","minimum":1,"maximum":10},"scope":{"default":{"activeCategoryId":null,"requiredFilterCategoryIds":[]},"type":"object","properties":{"activeCategoryId":{"default":null,"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"requiredFilterCategoryIds":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["activeCategoryId","requiredFilterCategoryIds"],"additionalProperties":false}},"required":["fragment","limit","scope"],"additionalProperties":false},"PublicPromptRecommendationResponse":{"type":"object","properties":{"apiVersion":{"type":"number","const":1},"catalogRevision":{"type":"string"},"mode":{"type":"string","enum":["lexical","hybrid"]},"state":{"type":"string","enum":["ready","lexical-fallback"]},"fallbackReason":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"source":{"type":"string","enum":["lexical","semantic","hybrid"]},"matchedFields":{"type":"array","items":{"type":"string","enum":["name","alias","wordForm","description","category"]}},"matchedTerms":{"type":"array","items":{"type":"string"}},"token":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"wordForms":{"type":"array","items":{"type":"string"}},"categoryIds":{"type":"array","items":{"type":"string"}},"exampleCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"coverImageUrl":{"type":"string"},"previewImageUrls":{"type":"array","items":{"type":"string"}},"links":{"type":"object","properties":{"api":{"type":"string"},"html":{"type":"string"}},"required":["api","html"],"additionalProperties":false}},"required":["id","name","description","aliases","wordForms","categoryIds","exampleCount","previewImageUrls","links"],"additionalProperties":false}},"required":["rank","source","matchedFields","matchedTerms","token"],"additionalProperties":false}},"fragment":{"type":"string"}},"required":["apiVersion","catalogRevision","mode","state","results","fragment"],"additionalProperties":false}}}}