Partner API v1
Machine-to-machine API for submitting scripts, polling review status, retrieving reports, and receiving webhooks. All paths below are relative to the production base URL below.
Base URL
https://quilty.app/api/v1/partner Authentication
Send a bearer token on every request (except POST /attribution/capture, which is public for landing
pages):
Authorization: Bearer qpk_live_… # or qpk_test_… in sandbox Keys are scoped. Typical scopes include reviews:write, reviews:read, provenance:read, and webhooks:manage.
Idempotency
POST requests that create or mutate state require an Idempotency-Key header. Replaying the
same key with the same body returns the original response; a different body returns 409 idempotency_conflict.
Error shape
{
"error": {
"code": "not_found",
"message": "…"
}
} Core endpoints (summary)
POST /attribution/capture— public; records partner landing attribution (sets a first-party cookie). Body:partner_slug, optionalexternal_ref(e.g.?ref=), optionalvisitor_id, optionallanding_path.POST /reviews— submit a script file (multipart); optionalexternal_ref, services, callback URL, etc.GET /reviews— list reviews (cursor pagination).GET /reviews/{review_id}— review status and progress.GET /reviews/{review_id}/report— JSON report when ready.GET /reviews/{review_id}/report.pdf— PDF when ready.DELETE /reviews/{review_id}— request deletion / retention per policy.POST /webhooks— register a URL and events; response includes a signing secret (prefixwhsec_).GET /webhooks,DELETE /webhooks/{webhook_id}— manage subscriptions.
Use the OpenAPI-backed description in the backend (or your integration tests) for full request/response fields.
Webhook signature
Each delivery is an HTTP POST with a JSON body. Quilty sends:
X-Quilty-Signature: t=<unix_timestamp>,v1=<hex_hmac> Compute HMAC-SHA256 over the raw request body bytes, prefixed with the timestamp and a dot: <t>. concatenated with the body, using your webhook secret (the whsec_… value from registration). Compare v1 to the hex digest using a constant-time comparison.
Reject deliveries where the absolute time skew is greater than 300 seconds.
Failed deliveries are retried with exponential backoff for up to 24 hours.
Landing pages
Human referrals can start at /partner/[partner_slug] (for example /partner/copysight). Pass ?ref=… to record an external reference alongside attribution.