{"openapi":"3.1.0","info":{"title":"TraceHumanity API","description":"Programmatic access to human-origin certification: detect TrustMark watermarks in images, look up certificates, verify provenance. Authenticate with `Authorization: Bearer th_live_...`. Create keys at /api-keys.","version":"1.0.0","contact":{"url":"https://tracehumanity.com/"},"license":{"name":"Commercial — TraceHumanity Terms"}},"servers":[{"url":"https://tracehumanity.com/api/v1","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/detect":{"post":{"tags":["Detection"],"summary":"Detect TrustMark watermark in an image","description":"Uploads an image and returns whether a TrustMark watermark is present. If present and registered, the associated certificate is returned. Charges 1 request unit.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Image file (max 20 MB)."}},"required":["file"]}}}},"responses":{"200":{"description":"Detection result","headers":{"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Daily request quota (integer or \"unlimited\" for ENTERPRISE)"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests for the current UTC day"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp of next quota reset (UTC midnight)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"File too large (over 20 MB)"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Watermark detection service not configured"}}}},"/certificates/{id}":{"get":{"tags":["Certificates"],"summary":"Look up a certificate by number or file hash","description":"Returns the certificate matching either the certificate number (e.g. `TH-2026-001234`) or the SHA-256 hash of the original file. Anonymous access is allowed (no auth); authenticated requests charge 1 quota unit per call.","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Certificate number (`TH-...`) or asset file SHA-256 hex hash."}],"responses":{"200":{"description":"Certificate found","headers":{"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Daily request quota (integer or \"unlimited\" for ENTERPRISE)"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests for the current UTC day"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp of next quota reset (UTC midnight)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CertificateBundle"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"No certificate found"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/certificates/batch":{"post":{"tags":["Certificates"],"summary":"Look up up to 50 certificates in one call","description":"Each id in the body charges 1 quota unit. Mixed batches of certificate numbers and file hashes are allowed. Results preserve input order.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"maxItems":50,"minItems":1}},"required":["ids"]}}}},"responses":{"200":{"description":"Batch results","headers":{"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Daily request quota (integer or \"unlimited\" for ENTERPRISE)"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests for the current UTC day"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp of next quota reset (UTC midnight)"}},"content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"found":{"type":"boolean"},"result":{"$ref":"#/components/schemas/CertificateBundle"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"th_live_...","description":"Issue and revoke keys from your dashboard at /api-keys."}},"responses":{"BadRequest":{"description":"Malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Daily rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"string"},"description":"Daily request quota (integer or \"unlimited\" for ENTERPRISE)"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests for the current UTC day"},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp of next quota reset (UTC midnight)"},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until quota resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"DetectResult":{"type":"object","properties":{"detected":{"type":"boolean"},"wmId":{"type":"string","nullable":true,"description":"Watermark id, 16-character hex. Null when not detected."},"confidence":{"type":"number","description":"Decoder confidence, 0–1."},"bitAccuracy":{"type":"number","description":"BCH error-correction bit accuracy."},"registered":{"type":"boolean","description":"True if wm_id is bound to a TraceHumanity certificate."},"certificate":{"$ref":"#/components/schemas/PublicCertificate","nullable":true},"signals":{"type":"object","nullable":true,"properties":{"c2pa":{"type":"string","enum":["verified","absent"]},"watermark":{"type":"string","enum":["matched","absent","detected_unregistered"]},"fingerprint":{"type":"string","enum":["matched","absent"]},"signature":{"type":"string","enum":["valid","invalid","absent"]}}}}},"CertificateBundle":{"type":"object","properties":{"found":{"type":"boolean","enum":[true]},"certificate":{"$ref":"#/components/schemas/PublicCertificate"},"signals":{"type":"object","properties":{"c2pa":{"type":"string","enum":["verified","absent"]},"watermark":{"type":"string","enum":["matched","absent"]},"fingerprint":{"type":"string","enum":["matched","absent"]},"signature":{"type":"string","enum":["valid","invalid","absent"]}}},"cryptographic":{"type":"object","properties":{"signatureAlgorithm":{"type":"string","nullable":true},"signatureValid":{"type":"boolean","nullable":true},"trustRegistryUrl":{"type":"string","format":"uri"}}}}},"PublicCertificate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"certificate_number":{"type":"string","example":"TH-2026-001234"},"level":{"type":"string","enum":["LEVEL_1","LEVEL_2","LEVEL_3","LEVEL_4","LEVEL_5"],"description":"Verification level."},"classification":{"type":"string"},"issued_at":{"type":"string","format":"date-time","nullable":true},"revoked":{"type":"boolean"},"revocation_reason":{"type":"string","nullable":true},"signature_present":{"type":"boolean"},"asset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"file_hash":{"type":"string"},"file_type":{"type":"string"}}},"owner":{"type":"object","properties":{"full_name":{"type":"string","nullable":true},"display_name":{"type":"string","nullable":true}}}}}}},"tags":[{"name":"Detection","description":"Detect TrustMark watermarks in images."},{"name":"Certificates","description":"Look up certificates by number or file hash."}]}