Developers

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, optional external_ref (e.g. ?ref=), optional visitor_id, optional landing_path.
  • POST /reviews — submit a script file (multipart); optional external_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 (prefix whsec_).
  • 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.