{"openapi":"3.1.0","info":{"title":"PixGuard Public API","summary":"Image copyright-risk scanning for agents and integrations.","description":"Scan images for copyright risk: watermarks, stock-agency fingerprint matches, AI-generation markers, EXIF/IPTC metadata and reverse-image source attribution. Authenticate with a PixGuard API key (X-API-Key: pg_live_...) or a Clerk session token (Authorization: Bearer ...). Scans are billed in credits; a cached image costs 0. PixGuard flags risk for review — it is not legal advice and a score is not a determination of infringement.","version":"5.1.0"},"servers":[{"url":"https://api.pixguard.io","description":"Production"}],"paths":{"/v2/me":{"get":{"tags":["v2"],"summary":"Get Me","description":"Return the caller's plan + credit snapshot.\n\nAuth: Authorization: Bearer <clerk-jwt>  OR  X-API-Key: pg_live_...\n\nNo external calls, no GPU usage, no credits consumed. Adds one indexed\nCOUNT over the caller's own scans to resolve effective_tier; at polling\nfrequency that is negligible, and it is the only way a client can tell a\nuser they are on a trial before it silently ends.","operationId":"get_me_v2_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/scan/image":{"post":{"tags":["v2"],"summary":"Scan Image","description":"Scan an uploaded image for copyright risk.\n\nRuns the full detection pipeline: hashing → CLIP → stock matching →\nwatermark/metadata detection → VLM (if triggered).\n\nCredits: a newly analysed image costs 1 credit, plus any optional feature\ncharges. A cached image costs 0. (Changed 2026-09-14 from 3 credits per\nimage; tier allowances were rescaled by the same factor, so the number of\nimages each plan buys is unchanged.)\n\n`remaining_balance` and GET /v2/me are authoritative for your balance.","operationId":"scan_image_v2_scan_image_post","parameters":[{"name":"skip_cache","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Skip Cache"}},{"name":"include_source","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Source"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_scan_image_v2_scan_image_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanImageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/scan/url":{"post":{"tags":["v2"],"summary":"Scan Url","description":"Scan an image by URL for copyright risk.\n\nDownloads the image and runs the full detection pipeline.","operationId":"scan_url_v2_scan_url_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanUrlRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanImageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/report/{report_id}":{"get":{"tags":["v2"],"summary":"Get Report","description":"Retrieve a scan report by ID.\n\nReturns the full analysis result including matches, VLM analysis,\nsource attribution, and metadata.","operationId":"get_report_v2_report__report_id__get","parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"integer","title":"Report Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/monitoring":{"post":{"tags":["v2"],"summary":"Create Monitoring","description":"Create a recurring monitoring subscription for a website.\n\nRe-scans the site on the chosen schedule and emails a summary of risky\nimages after each run. Requires Pro or Business.","operationId":"create_monitoring_v2_monitoring_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]},"get":{"tags":["v2"],"summary":"List Monitoring","description":"List user's monitoring subscriptions.","operationId":"list_monitoring_v2_monitoring_get","parameters":[{"name":"active_only","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Active Only"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MonitoringResponse"},"title":"Response List Monitoring V2 Monitoring Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/monitoring/{subscription_id}":{"delete":{"tags":["v2"],"summary":"Delete Monitoring","description":"Deactivate a monitoring subscription.","operationId":"delete_monitoring_v2_monitoring__subscription_id__delete","parameters":[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","title":"Subscription Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/inbox":{"get":{"tags":["v2"],"summary":"Get Risk Inbox","description":"Return the user's Risk Inbox — high-risk scan findings without a\ncompleted remediation action. Pending takedowns stay visible with a\ntakedown_filed_at timestamp so the UI can render an \"in-flight\"\nstate instead of hiding them.","operationId":"get_risk_inbox_v2_inbox_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InboxItem"},"title":"Response Get Risk Inbox V2 Inbox Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/v2/remediations":{"post":{"tags":["v2"],"summary":"Create Remediation","description":"Record a user action on an inbox finding.\n\naction_type must be one of: resolved, licensed, takedown.\n  - resolved / licensed: status -> 'completed', finding hidden from inbox.\n  - takedown:            status -> 'pending', finding stays in inbox\n                         with a \"takedown filed\" badge until the user\n                         marks it resolved or licensed.","operationId":"create_remediation_v2_remediations_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemediationCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemediationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"apiKey":[]},{"clerkBearer":[]}]}},"/health":{"get":{"summary":"Health Check","description":"Liveness check — is the process up.\n\nAlways 200 if the FastAPI process is running. For dependency-aware\nreadiness (what Cloudflare Worker should failover on), use /health/ready.\n\n/healthz is an alias for k8s-style probes and external monitors we\ndon't own. Hidden from the OpenAPI schema.","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Body_scan_image_v2_scan_image_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_scan_image_v2_scan_image_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InboxItem":{"properties":{"scan_result_id":{"type":"integer","title":"Scan Result Id"},"scan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scan Id"},"image_url":{"type":"string","title":"Image Url"},"image_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Hash"},"risk_score":{"type":"number","title":"Risk Score"},"severity":{"type":"string","title":"Severity"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url"},"analyzed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Analyzed At"},"takedown_filed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Takedown Filed At"},"source_attribution":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Attribution"}},"type":"object","required":["scan_result_id","image_url","risk_score","severity"],"title":"InboxItem","description":"One Risk Inbox finding. Mirrors the dict returned by\nremediation.list_inbox so the FE can render cards directly from\nthe JSON array."},"MeResponse":{"properties":{"email":{"type":"string","title":"Email"},"subscription_tier":{"type":"string","title":"Subscription Tier"},"credit_balance":{"type":"integer","title":"Credit Balance"},"images_remaining":{"type":"integer","title":"Images Remaining"},"subscription_credits":{"type":"integer","title":"Subscription Credits"},"purchased_credits":{"type":"integer","title":"Purchased Credits"},"effective_tier":{"type":"string","title":"Effective Tier"},"trial_scans_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Trial Scans Remaining"}},"type":"object","required":["email","subscription_tier","credit_balance","images_remaining","subscription_credits","purchased_credits","effective_tier"],"title":"MeResponse","description":"Account snapshot for the authenticated API client."},"MonitoringCreateRequest":{"properties":{"website_url":{"type":"string","title":"Website Url"},"frequency":{"type":"string","title":"Frequency","default":"weekly"},"alert_email":{"type":"boolean","title":"Alert Email","default":true},"alert_webhook_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Alert Webhook Url"},"alert_on_severity":{"type":"string","title":"Alert On Severity","default":"medium"}},"type":"object","required":["website_url"],"title":"MonitoringCreateRequest"},"MonitoringResponse":{"properties":{"id":{"type":"string","title":"Id"},"website_url":{"type":"string","title":"Website Url"},"is_active":{"type":"boolean","title":"Is Active"},"frequency":{"type":"string","title":"Frequency"},"alert_on_severity":{"type":"string","title":"Alert On Severity"},"last_scan_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scan At"},"next_scan_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Scan At"},"total_scans_run":{"type":"integer","title":"Total Scans Run"},"total_alerts_sent":{"type":"integer","title":"Total Alerts Sent"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","website_url","is_active","frequency","alert_on_severity","total_scans_run","total_alerts_sent","created_at"],"title":"MonitoringResponse"},"RemediationCreateRequest":{"properties":{"image_url":{"type":"string","title":"Image Url"},"action_type":{"type":"string","title":"Action Type"},"scan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scan Id"},"image_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Hash"},"original_risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Original Risk Score"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"}},"type":"object","required":["image_url","action_type"],"title":"RemediationCreateRequest","description":"Body for POST /v2/remediations — record a user action on an inbox\nfinding. action_type is one of: resolved, licensed, takedown."},"RemediationResponse":{"properties":{"id":{"type":"integer","title":"Id"},"image_url":{"type":"string","title":"Image Url"},"action_type":{"type":"string","title":"Action Type"},"status":{"type":"string","title":"Status"},"scan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scan Id"},"original_risk_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Original Risk Score"},"created_at":{"type":"string","title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","image_url","action_type","status","created_at"],"title":"RemediationResponse"},"ReportResponse":{"properties":{"id":{"type":"integer","title":"Id"},"filename":{"type":"string","title":"Filename"},"risk_score":{"type":"number","title":"Risk Score"},"severity":{"type":"string","title":"Severity"},"matches":{"items":{},"type":"array","title":"Matches"},"vlm_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Vlm Analysis"},"source_attribution":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Attribution"},"credits_deducted":{"type":"integer","title":"Credits Deducted"},"was_cached":{"type":"boolean","title":"Was Cached"},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","filename","risk_score","severity","matches","credits_deducted","was_cached","created_at"],"title":"ReportResponse"},"ScanImageResponse":{"properties":{"report_id":{"type":"integer","title":"Report Id"},"risk_score":{"type":"number","title":"Risk Score"},"severity":{"type":"string","title":"Severity"},"matches":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Matches"},"credits_deducted":{"type":"integer","title":"Credits Deducted"},"remaining_balance":{"type":"integer","title":"Remaining Balance"},"cached":{"type":"boolean","title":"Cached"},"stock_match":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Stock Match"},"source_attribution":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Attribution"},"vlm_analysis":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Vlm Analysis"},"disclaimer":{"type":"string","title":"Disclaimer"}},"type":"object","required":["report_id","risk_score","severity","matches","credits_deducted","remaining_balance","cached","disclaimer"],"title":"ScanImageResponse"},"ScanUrlRequest":{"properties":{"url":{"type":"string","title":"Url"},"include_source":{"type":"boolean","title":"Include Source","default":false},"skip_cache":{"type":"boolean","title":"Skip Cache","default":false}},"type":"object","required":["url"],"title":"ScanUrlRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"PixGuard API key (pg_live_...). Business tier."},"clerkBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk session token issued by the PixGuard web app."}}},"tags":[{"name":"v2","description":"Stable public API surface."}],"externalDocs":{"description":"Human documentation","url":"https://www.pixguard.io/docs/api"}}