{"openapi":"3.1.0","info":{"title":"IPzest API","version":"1.0.0","description":"Read-only access to your monitoring data: the brand, its violations, their history and evidence. Authenticate with an API key from Settings as a bearer token. Every violation is returned in one flat shape, the same one the dashboard exports and webhooks deliver."},"servers":[{"url":"https://dashboard.ipzest.app/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer ipz_live_…"}},"schemas":{"Violation":{"type":"object","properties":{"id":{"type":"string","title":"ID"},"brand":{"type":"string","title":"Brand"},"market":{"type":"string","description":"National marketplace site the listing was found on: US, GB, DE, IT, FR or ES. Empty on older records.","title":"Market"},"platform":{"type":"string","title":"Platform"},"listing_url":{"type":"string","title":"Listing URL"},"seller":{"type":"string","title":"Seller"},"title":{"type":"string","title":"Title"},"severity":{"type":"string","enum":["low","medium","high","critical"],"title":"Severity"},"risk_score":{"type":"number","description":"Assessment confidence, 0 to 100; empty when not scored.","title":"Risk score"},"listing_type":{"type":"string","enum":["","counterfeit","reseller","authorized","accessory","noise"],"title":"Listing type"},"status":{"type":"string","enum":["pending","investigating","takedown_sent","resolved","escalated"],"title":"Status"},"takedown_outcome":{"type":"string","enum":["","sent","removed","relisted","still_active","unreachable","unknown"],"title":"Takedown outcome"},"detected_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Detected at"},"updated_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Updated at"},"takedown_drafted_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Takedown drafted at"},"takedown_sent_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Takedown sent at"},"removed_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Removed at"},"relisted_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC. Empty when the event has not happened.","title":"Relisted at"},"evidence_count":{"type":"integer","title":"Evidence files"},"has_screenshot":{"type":"boolean","title":"Has screenshot"},"evidence_bundle_url":{"type":"string","title":"Evidence bundle URL"}}},"HistoryEvent":{"type":"object","properties":{"violation_id":{"type":"string"},"at":{"type":"string","format":"date-time"},"event":{"type":"string","description":"detected, severity_overridden, takedown_drafted, takedown_sent, outcome_<value>, response_received, action_created, action_sent, action_response, action_resolved"},"detail":{"type":"string"},"source":{"type":"string"}}},"EvidenceFile":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string"},"kind":{"type":"string","enum":["screenshot","page_snapshot","detection_record","file"]},"url":{"type":"string","description":"Fetch with the same bearer key."}}},"WebhookPayload":{"type":"object","properties":{"id":{"type":"string","description":"Delivery id; also sent as X-IPzest-Delivery."},"event":{"type":"string","enum":["violation.created","violation.status_changed","violation.severity_changed","takedown.outcome_changed","ping"]},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Violation"},"previous":{"type":"object","description":"The prior value of the field that changed, e.g. { \"status\": \"pending\" }."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}},"paths":{"/brand":{"get":{"summary":"The brand this key monitors","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"markets":{"type":"array","items":{"type":"string"}},"authorized_sellers":{"type":"array","items":{"type":"string"}},"own_store_domains":{"type":"array","items":{"type":"string"}}}}}}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations":{"get":{"summary":"List violations","description":"Newest first. With updated_since, oldest change first: keep the highest updated_at you have seen and pass it back to sync. A page can hold fewer than `limit` rows while next_cursor is still set; only a null next_cursor means the end.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","investigating","takedown_sent","resolved","escalated"]}},{"name":"severity","in":"query","schema":{"type":"string","enum":["low","medium","high","critical"]}},{"name":"market","in":"query","schema":{"type":"string","enum":["US","GB","DE","IT","FR","ES"]}},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Listing host, e.g. ebay.it or amazon.de."},{"name":"brand","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Detected on or after."},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"},"description":"Detected on or before."},{"name":"updated_since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed after; switches ordering to oldest change first."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Violation"}},"next_cursor":{"type":["string","null"]}}}}}},"400":{"description":"A filter value is invalid; the message says which.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/export.csv":{"get":{"summary":"Violations as CSV","description":"Same filters as the list, up to 10,000 rows. X-Export-Rows and X-Export-Truncated headers report the count.","responses":{"200":{"description":"CSV with a UTF-8 byte-order mark.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/{id}":{"get":{"summary":"One violation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Violation id, from the list endpoint."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Violation"},{"type":"object","properties":{"description":{"type":"string"},"detection_reason_code":{"type":"string"},"outcome_history":{"type":"array","items":{"type":"object","properties":{"outcome":{"type":"string"},"at":{"type":"string"},"source":{"type":"string"}}}}}}]}}}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"404":{"description":"Not on this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/{id}/history":{"get":{"summary":"Everything that happened to a violation, oldest first","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Violation id, from the list endpoint."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEvent"}}}}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/{id}/evidence":{"get":{"summary":"Evidence files on a violation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Violation id, from the list endpoint."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceFile"}},"bundle_url":{"type":["string","null"]}}}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/{id}/evidence/{index}":{"get":{"summary":"One evidence file","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Violation id, from the list endpoint."},{"name":"index","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The file, streamed with its own content type."},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}},"/violations/{id}/evidence.zip":{"get":{"summary":"Evidence bundle","description":"The takedown notice, page snapshot, screenshot, detection record and a manifest of SHA-256 hashes, as one archive.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Violation id, from the list endpoint."}],"responses":{"200":{"description":"ZIP archive.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing, unknown or revoked key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"403":{"description":"The account's plan does not include API access.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}},"429":{"description":"Burst (120/min) or daily (5,000/day) limit reached.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","plan_required","rate_limited","not_found","invalid_request","internal"]},"message":{"type":"string"}}}}}}}}}}}},"x-webhooks":{"description":"Configured in Settings → Webhooks. Each delivery is an HTTPS POST with a JSON WebhookPayload, headers X-IPzest-Event, X-IPzest-Delivery and X-IPzest-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" using the endpoint secret>). Reject timestamps older than five minutes. Respond 2xx within ten seconds; anything else is retried with backoff for about a day.","events":["violation.created","violation.status_changed","violation.severity_changed","takedown.outcome_changed"]}}