{"openapi":"3.1.0","info":{"title":"Cikada Vision API","version":"1.0.0","description":"Garment classification for sorting lines. Send images, receive typed attributes with confidence, correct them, export them. Every request is scoped to the organization that owns the API key.","contact":{"name":"Cikada Solutions AB"}},"servers":[{"url":"https://vision.cikadasolutions.com/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Items","description":"Garments and their classifications"},{"name":"Classification","description":"Synchronous classification for low-latency robot use"},{"name":"Batches","description":"Groups of items, such as one robot run"},{"name":"Webhooks","description":"Signed event deliveries with retries"},{"name":"Reference","description":"Taxonomy and health"}],"paths":{"/health":{"get":{"tags":["Reference"],"summary":"Service health","security":[],"responses":{"200":{"description":"Component status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/taxonomy":{"get":{"tags":["Reference"],"summary":"Current enums and grading rubric","description":"Fetch once and validate locally before sending corrections.","responses":{"200":{"description":"Taxonomy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Taxonomy"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items":{"post":{"tags":["Items"],"summary":"Create an item and queue classification","description":"Multipart: fields image[] (1–8 files, JPEG/PNG/WebP/HEIC, 20 MB each), view[] (front|back|label|detail), external_ref, robot_id, batch_id. Or JSON with image_urls for pre-hosted HTTPS images. Send an Idempotency-Key header to make retries safe for 24 hours.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image[]"],"properties":{"image[]":{"type":"array","items":{"type":"string","format":"binary"}},"view[]":{"type":"array","items":{"type":"string","enum":["front","back","label","detail","unknown"]}},"external_ref":{"type":"string","maxLength":120},"robot_id":{"type":"string","format":"uuid"},"batch_id":{"type":"string","format":"uuid"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/CreateItemJson"}}}},"responses":{"202":{"description":"Item queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemAccepted"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Items"],"summary":"List items","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["queued","processing","classified","reviewed","failed"]}},{"name":"batch_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Page of items, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemList"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}":{"get":{"tags":["Items"],"summary":"Get an item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Item with images, current attributes and prediction history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}/classify":{"post":{"tags":["Items"],"summary":"Re-run classification","description":"Queues a new prediction, for example after adding a label image. Existing predictions and corrections are kept.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Item queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemAccepted"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/items/{id}/attributes":{"patch":{"tags":["Items"],"summary":"Submit human corrections","description":"Each changed attribute becomes a new human row beside the model row. Emits item.reviewed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchAttributes"}}}},"responses":{"200":{"description":"Corrections written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchResult"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/classify/sync":{"post":{"tags":["Classification"],"summary":"Classify synchronously","description":"Same body as POST /items. The item is stored, classified inline and returned in full. Target p95 under 15 s.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image[]"],"properties":{"image[]":{"type":"array","items":{"type":"string","format":"binary"}},"view[]":{"type":"array","items":{"type":"string"}},"external_ref":{"type":"string"},"robot_id":{"type":"string","format":"uuid"},"batch_id":{"type":"string","format":"uuid"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/CreateItemJson"}}}},"responses":{"200":{"description":"Classified item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Item"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The model failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches":{"post":{"tags":["Batches"],"summary":"Create a batch","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatch"}}}},"responses":{"201":{"description":"Batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}":{"get":{"tags":["Batches"],"summary":"Get a batch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/batches/{id}/export":{"get":{"tags":["Batches"],"summary":"Export a batch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["csv","json"],"default":"json"}}],"responses":{"200":{"description":"All items in the batch","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}}}}},"text/csv":{"schema":{"type":"string"},"example":"id,status,...\r\n"}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook","description":"Deliveries are JSON POSTs `{ event, item_id, org_id, occurred_at, data }` with `X-Cikada-Signature: sha256=HMAC-SHA256(secret, body)`. Failed deliveries retry after 1 m, 5 m, 30 m, 2 h and 12 h. The secret is returned once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhook"}}}},"responses":{"201":{"description":"Webhook created; includes the secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Request failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhooks","responses":{"200":{"description":"Webhooks without secrets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Recent deliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Newest first","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"ck_live_…","description":"Scopes: items:read, items:write, classify, batches, webhooks"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["validation_error","unauthorized","forbidden","not_found","rate_limited","model_error","internal"]},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every failure, on every endpoint."},"Health":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"db":{"type":"string","enum":["ok","error"]},"storage":{"type":"string","enum":["ok","error"]},"model":{"type":"string"},"version":{"type":"string"}},"required":["status","db","storage","model","version"],"additionalProperties":false},"Taxonomy":{"type":"object","properties":{"version":{"type":"string"},"enums":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"rubric":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"attributes":{"type":"array","items":{"type":"string"}}},"required":["version","enums","rubric","attributes"],"additionalProperties":false},"Item":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","enum":["queued","processing","classified","reviewed","failed"]},"source":{"type":"string","enum":["upload","camera","robot","api"]},"external_ref":{"type":["string","null"]},"batch_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"robot_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"site_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"classified_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"reviewed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"images":{"type":"array","items":{"$ref":"#/components/schemas/ItemImage"}},"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"$ref":"#/components/schemas/Attribute"}},"classification":{"anyOf":[{"$ref":"#/components/schemas/GarmentClassification"},{"type":"null"}],"description":"Latest full model output, validated against the contract"},"predictions":{"type":"array","items":{"$ref":"#/components/schemas/Prediction"}}},"required":["id","status","source","external_ref","batch_id","robot_id","site_id","error","created_at","classified_at","reviewed_at","images","attributes","classification","predictions"],"additionalProperties":false},"ItemAccepted":{"type":"object","properties":{"item_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"status":{"type":"string","const":"queued"}},"required":["item_id","status"],"additionalProperties":false},"ItemList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"next_cursor":{"type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false},"CreateItemJson":{"type":"object","properties":{"image_urls":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","format":"uri"}},"views":{"type":"array","items":{"type":"string","enum":["front","back","label","detail","unknown"]}},"external_ref":{"type":"string","maxLength":120},"robot_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"batch_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["image_urls"],"additionalProperties":false,"description":"Alternative to multipart: images already hosted at HTTPS URLs."},"PatchAttributes":{"type":"object","properties":{"attributes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","minLength":1,"maxLength":60}},"reviewer":{"type":"string","minLength":1,"maxLength":80}},"required":["attributes","reviewer"],"additionalProperties":false},"PatchResult":{"type":"object","properties":{"item_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"corrections":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["item_id","corrections"],"additionalProperties":false},"CreateBatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"source":{"default":"robot","type":"string","enum":["upload","camera","robot","api"]}},"required":["name","source"],"additionalProperties":false},"Batch":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"source":{"type":"string","enum":["upload","camera","robot","api"]},"item_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","source","item_count","created_at"],"additionalProperties":false},"Attribute":{"type":"object","properties":{"value":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string","enum":["model","human"]},"evidence":{"type":["string","null"]}},"required":["value","confidence","source"],"additionalProperties":false,"description":"Current value of one attribute: latest human correction if any, else the latest model value."},"ItemImage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view":{"type":"string","enum":["front","back","label","detail","unknown"]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"width":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"height":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"urls":{"type":"object","properties":{"original":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"model_input":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"thumbnail":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["original","model_input","thumbnail"],"additionalProperties":false,"description":"Signed URLs valid for one hour"}},"required":["id","view","position","width","height","urls"],"additionalProperties":false},"Prediction":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"model":{"type":"string"},"prompt_version":{"type":"string"},"latency_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"input_tokens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"output_tokens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","model","prompt_version","latency_ms","input_tokens","output_tokens","attempts","created_at"],"additionalProperties":false},"CreateWebhook":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["item.classified","item.reviewed"]}},"description":{"type":"string","maxLength":200}},"required":["url","events"],"additionalProperties":false},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"description":{"type":["string","null"]},"failure_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_delivery_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"secret":{"description":"Only present in the creation response","type":"string"}},"required":["id","url","events","active","description","failure_count","last_delivery_at","created_at"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed","exhausted"]},"status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_retry_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"delivered_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"last_error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","event","status","status_code","attempts","next_retry_at","delivered_at","last_error","created_at"],"additionalProperties":false},"GarmentClassification":{"type":"object","properties":{"garment_type":{"type":"object","properties":{"value":{"type":"string","enum":["t_shirt","shirt","blouse","polo","tank_top","sweater","cardigan","hoodie","sweatshirt","vest","jeans","trousers","shorts","skirt","leggings","joggers","dress","jumpsuit","overalls","jacket","coat","blazer","parka","raincoat","underwear","socks","swimwear","sportswear","nightwear","scarf","hat","gloves","bag","shoes","home_textile","workwear","other","unknown"],"description":"Type of garment"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"garment_category":{"type":"object","properties":{"value":{"type":"string","enum":["tops","bottoms","full_body","outerwear","underwear","accessories","footwear","home_textile","other","unknown"],"description":"Category the garment type belongs to"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"primary_color":{"type":"object","properties":{"value":{"type":"string","enum":["black","white","grey","navy","blue","light_blue","green","olive","red","burgundy","pink","purple","orange","yellow","beige","brown","cream","multicolor","unknown"],"description":"Colour covering most of the garment"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"secondary_color":{"type":"object","properties":{"value":{"type":"string","enum":["black","white","grey","navy","blue","light_blue","green","olive","red","burgundy","pink","purple","orange","yellow","beige","brown","cream","multicolor","none","unknown"],"description":"Second most prominent colour, or none"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"color_hex":{"type":"object","properties":{"value":{"anyOf":[{"type":"string","pattern":"^#[0-9A-F]{6}$","description":"Dominant colour as an uppercase hex value like #1B4D3E"},{"type":"string","const":"unknown"}]},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"pattern":{"type":"object","properties":{"value":{"type":"string","enum":["solid","striped","checked","floral","graphic_print","logo_print","dotted","camouflage","animal","abstract","other","unknown"],"description":"Surface pattern"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"condition_grade":{"type":"object","properties":{"value":{"type":"string","enum":["A","B","C","D","unknown"],"description":"Condition grade A to D per the rubric"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"defects":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["stain","hole","tear","pilling","fading","missing_button","broken_zipper","stretched","odor_visible_signs","discoloration","other"]},"severity":{"type":"string","enum":["minor","moderate","severe"]},"location":{"type":"string","maxLength":60,"description":"Where on the garment, at most 60 characters"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"}},"required":["type","severity","location","confidence"],"additionalProperties":false}},"recommended_route":{"type":"object","properties":{"value":{"type":"string","enum":["reuse","repair","recycle_fiber","waste","unknown"],"description":"Recommended handling route"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"material_primary":{"type":"object","properties":{"value":{"type":"string","enum":["cotton","polyester","wool","viscose","linen","nylon","acrylic","elastane","silk","cashmere","denim_cotton","leather","blend","unknown"],"description":"Main fibre"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"material_composition":{"type":"array","items":{"type":"object","properties":{"fiber":{"type":"string","description":"Fibre name as printed on the care label"},"percent":{"type":"number","minimum":0,"maximum":100,"description":"Percentage 0 to 100"}},"required":["fiber","percent"],"additionalProperties":false},"description":"Only from a visible care label. Empty when no label is readable."},"material_source":{"type":"string","enum":["care_label_ocr","visual_estimate","unknown"]},"brand":{"type":"object","properties":{"value":{"type":"string","maxLength":60,"description":"Brand from a visible label or unmistakable logo. Use \"unknown\" when not visible."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"size":{"type":"object","properties":{"value":{"type":"string","maxLength":12,"description":"Size from a visible label. Use \"unknown\" when not visible."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"gender_segment":{"type":"object","properties":{"value":{"type":"string","enum":["women","men","unisex","kids","baby","unknown"],"description":"Intended wearer"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"sleeve_length":{"type":"object","properties":{"value":{"type":"string","enum":["sleeveless","short","three_quarter","long","not_applicable","unknown"],"description":"Sleeve length"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"closure":{"type":"object","properties":{"value":{"type":"string","enum":["none","buttons","zipper","hook","drawstring","velcro","other","unknown"],"description":"Main closure"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"season":{"type":"object","properties":{"value":{"type":"string","enum":["summer","winter","all_season","unknown"],"description":"Season the garment is made for"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence between 0 and 1"},"evidence":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["value","confidence"],"additionalProperties":false},"care_label_text":{"description":"Verbatim text of a visible care label, or null","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"notes":{"description":"Anything an operator should know, or null","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["garment_type","garment_category","primary_color","secondary_color","color_hex","pattern","condition_grade","defects","recommended_route","material_primary","material_composition","material_source","brand","size","gender_segment","sleeve_length","closure","season"],"additionalProperties":false,"description":"Full model output: every attribute with a 0–1 confidence, defects, composition and label text."}}},"x-error-codes":["validation_error","unauthorized","forbidden","not_found","rate_limited","model_error","internal"]}