{"openapi":"3.1.0","info":{"title":"PolyReID Person Re-Identification API","version":"1.0.0","description":"Turn one person crop into a 768-dimensional, L2-normalized person-appearance embedding for similarity retrieval and human review. Outputs are probabilistic and are not proof of identity. Vectors are comparable only when model_revision and preprocess_version match.","termsOfService":"https://polyreid.com/legal/api-terms","contact":{"url":"https://polyreid.com/api"},"x-ai-transparency":{"disclosure_version":"2026-07-24.1","last_reviewed":"2026-07-24","model_card_url":"https://polyreid.com/legal/ai-transparency","intended_purpose":"Generate person-appearance embeddings from individual person crops for similarity retrieval, offline event-photo organisation and human-in-the-loop review.","ai_act_assessment_status":"EU AI Act classification under legal assessment","conformity_claim":false}},"externalDocs":{"description":"AI transparency, model card and instructions for use","url":"https://polyreid.com/legal/ai-transparency"},"servers":[{"url":"https://polyreid.com"}],"tags":[{"name":"Embeddings"}],"paths":{"/api/v1/embeddings":{"post":{"tags":["Embeddings"],"operationId":"createEmbedding","summary":"Create a person ReID embedding","security":[{"DeveloperApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Valid for 24 hours. Reusing it with a different payload returns 409."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary","description":"JPEG, PNG or WebP; at most 10 MB and 25 megapixels."},"retention":{"type":"string","enum":["none","30d"],"default":"none"},"model":{"type":"string","enum":["polyreid-person-reid-v1"],"default":"polyreid-person-reid-v1"}}}}}},"responses":{"200":{"description":"Embedding created or replayed idempotently","headers":{"Idempotent-Replayed":{"schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/ImageTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMedia"},"422":{"$ref":"#/components/responses/InvalidInput"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"},"504":{"$ref":"#/components/responses/Timeout"}}}},"/api/v1/embeddings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Embeddings"],"operationId":"getRetainedEmbedding","summary":"Get an unexpired retained embedding","security":[{"DeveloperApiKey":[]}],"responses":{"200":{"description":"Retained embedding","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Embedding not found or expired","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Embeddings"],"operationId":"deleteRetainedEmbedding","summary":"Delete a retained embedding early","description":"Deletion is immediate and does not refund the successful embedding.","security":[{"DeveloperApiKey":[]}],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Embedding not found or expired","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"DeveloperApiKey":{"type":"http","scheme":"bearer","bearerFormat":"preid_live_…"}},"schemas":{"EmbeddingResponse":{"type":"object","required":["id","request_id","model","model_revision","preprocess_version","embedding","dimensions","dtype","normalized","retention","expires_at","charged_usd"],"properties":{"id":{"type":"string"},"request_id":{"type":"string"},"model":{"type":"string","const":"polyreid-person-reid-v1"},"model_revision":{"type":"string","pattern":"^[a-f0-9]{64}$"},"preprocess_version":{"type":"string","const":"person-crop-256x128-v1"},"embedding":{"type":"array","minItems":768,"maxItems":768,"items":{"type":"number","format":"float"}},"dimensions":{"type":"integer","const":768},"dtype":{"type":"string","const":"float32"},"normalized":{"type":"boolean","const":true},"retention":{"type":"string","enum":["none","30d"]},"expires_at":{"type":["string","null"],"format":"date-time"},"charged_usd":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$"},"balance_usd":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$"}}}},"responses":{"Unauthorized":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"PaymentRequired":{"description":"Insufficient credits or suspended negative wallet","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"Conflict":{"description":"Idempotency collision or request already processing","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"ImageTooLarge":{"description":"Byte or pixel limit exceeded","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"UnsupportedMedia":{"description":"Unsupported actual image format","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"InvalidInput":{"description":"Malformed image or invalid request field","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"RateLimited":{"description":"Rate or concurrency limit exceeded","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"Unavailable":{"description":"Inference temporarily unavailable; not charged","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}},"Timeout":{"description":"Inference timed out; not charged","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":["string","null"]},"details":{"type":"object","additionalProperties":true}}}}}}}}}}}