{"openapi":"3.1.0","info":{"title":"polinket API","version":"1.0.0","description":"Search AI-generated low-poly GLB items by tag. Tags are lowercase English, hyphen-separated. All assets are CC0 1.0. Models are real-scale (1 unit = 1 m), glTF Y-up, with the bottom at y=0. The front faces +Z (the glTF 2.0 forward); existing items are still being aligned to this, so report one that faces another way as feedback with reason \"orientation\". Search queries (tags, hit count, client, session) are logged without IP addresses, and feedback sent to /api/polinket/feedback is used to fix models, tags, and to decide what to model next.","license":{"name":"CC0-1.0","identifier":"CC0-1.0"}},"servers":[{"url":"https://oto-nari.com"}],"externalDocs":{"description":"Web UI","url":"https://oto-nari.com/polinket/"},"components":{"schemas":{"Item":{"type":"object","required":["id","tags","polys","bytes","glb_url","thumb_url"],"properties":{"id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"polys":{"type":"integer","description":"Triangle count"},"bytes":{"type":"integer","description":"GLB file size in bytes"},"model":{"type":"string","description":"Generator model"},"created":{"type":"string","format":"date"},"glb_url":{"type":"string","format":"uri"},"thumb_url":{"type":"string","format":"uri"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Feedback":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["item","missing","endorse"],"description":"item: rate an item you looked at or used. missing: you could not find what you needed. endorse: stance on the Polinket whitepaper."},"item_id":{"type":"string","description":"Required for kind=item"},"rating":{"type":"integer","enum":[1,-1],"description":"Required for kind=item. 1 = usable, -1 = not usable"},"reasons":{"type":"array","maxItems":5,"items":{"type":"string","enum":["good-fit","wrong-object","floating-part","intersection","missing-part","scale","orientation","too-heavy","material","style-mismatch","bad-tags"]},"description":"For kind=item. Why it was or was not usable"},"payload":{"type":"string","maxLength":100,"description":"For kind=item. Optional free-form note of up to 100 characters, e.g. what you did with the item or what was wrong"},"wanted":{"type":"string","maxLength":200,"description":"Required for kind=missing. The object you were looking for, in plain English"},"tried":{"type":"array","maxItems":10,"items":{"type":"string","maxLength":100},"description":"For kind=missing. The tag queries you tried, e.g. [\"park-bench\", \"bench,park\"]"},"stance":{"type":"string","enum":["support","conditional","skeptical"],"description":"Required for kind=endorse"},"role":{"type":"string","enum":["previz","3d-artist","game-dev","film-video","developer","researcher","ai-agent","other"],"description":"For kind=endorse"},"query":{"type":"string","maxLength":200,"description":"The tags query that led to the item"},"task":{"type":"string","maxLength":200,"description":"What the item was for, e.g. \"props for a park scene\""},"comment":{"type":"string","maxLength":500},"client":{"type":"string","maxLength":64},"session":{"type":"string","maxLength":64}}}}},"paths":{"/api/polinket/tags":{"get":{"operationId":"listTags","summary":"List available tags with item counts. Call this first to learn the vocabulary.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Prefix filter"},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":500}}],"responses":{"200":{"description":"Tags sorted by item count","content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"}}}}}}}}}}}},"/api/polinket/search":{"get":{"operationId":"searchItems","summary":"Search items by tags.","parameters":[{"name":"tags","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated tags"},{"name":"match","in":"query","schema":{"type":"string","enum":["all","any"],"default":"all"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous response"},{"name":"client","in":"query","schema":{"type":"string","maxLength":64},"description":"Who is calling, e.g. \"my-agent/1.0\". Logged with the query to improve the library."},{"name":"session","in":"query","schema":{"type":"string","maxLength":64},"description":"Opaque id that groups the searches of one task. Do not put personal data here."}],"responses":{"200":{"description":"Matching items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"total":{"type":"integer","description":"Number of matching items across all pages"},"next_cursor":{"type":["string","null"]},"unknown_tags":{"type":"array","items":{"type":"string"}},"suggestions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}},"400":{"description":"tags missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/polinket/items/{id}":{"get":{"operationId":"getItem","summary":"Get one item with glb_url and thumb_url.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/polinket/feedback":{"post":{"operationId":"sendFeedback","summary":"Tell us whether an item worked for you, or what you could not find. Send one after using or rejecting an item, and one when a search came up empty.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"responses":{"201":{"description":"Recorded"},"400":{"description":"Invalid body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}