GetAff
Sign inList my program
API documentation

Changelog

The versions of the API contract, newest first. All of them are compatible: a client written for 1.0 still works.

Current version
v1 · 1.2.0

How versions work

The path carries the major version (/v1); info.version in the OpenAPI document carries the compatible changes listed here. All of them are additive: no field removed, no required field added. A breaking change would become /v2, served alongside. Each entry carries the date of the change.

1.2.0 — Signed webhooks.

  • Webhook endpoints: GET and POST /v1/webhooks, GET, PATCH and DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}/rotate and POST /v1/webhooks/{id}/test. Reading needs read, every change write; up to ten endpoints per account.
  • Four events — search.finished, prospect.replied, application.received, partner.approved — signed per the Standard Webhooks specification (webhook-id, webhook-timestamp, webhook-signature). The whsec_ secret is shown once; after a rotation the old one co-signs for 24 hours.
  • A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours. Payloads carry identifiers and counts, never an e-mail address or a message.
  • Webhooks are not exposed as MCP tools: their secrets would end up in assistant transcripts.
  • An unknown path under /api/v1 now answers 404 not_found as application/problem+json, after authentication, instead of an HTML page.

1.1.0 — Partner recruiting over the API, and the MCP server.

  • 29 new operations for everything the recruiting screens do: sites, criteria and their generated topic terms, the partner search and its latest results, the shortlist and its conversion to prospects, prospects and the paid e-mail lookup, the conversational search, the creator index (search, profile, lookalikes, the library of creators found), competitors, and outreach — mailboxes, sequences, enrolment. No endpoint sends an e-mail directly.
  • Scopes read, search, write and spend; keys created before 1.1 keep exactly read.
  • Cost confirmation: an operation that spends provider credits needs spend and a confirmCost at least equal to the estimate; otherwise it answers 402 cost_confirmation_required with the estimate in error.details and spends nothing. Confirmed spends are audited.
  • Idempotency-Key on writes (24 hours, successes only), request bodies capped at 32 KiB (413 payload_too_large), an account-wide rate limit on top of the per-key one, and 20 new error codes.
  • The MCP server at /api/mcp (Streamable HTTP, protocol versions 2025-11-25 back to 2024-11-05): 29 tools mirroring the API, with the same keys and scopes; paid tools confirm in two steps with a confirmToken.

  • Saved searches: GET /v1/sites/{id}/partner-search/history and /history/{searchId}; MCP tools list_saved_searches and get_saved_search.
  • Errors become RFC 9457 problem documents (application/problem+json: type, title, status, detail, instance) that keep the 1.0 error member unchanged; each type leads to its row on the errors page. 401 and 403 carry WWW-Authenticate.
  • RateLimit-Policy and RateLimit (IETF draft) next to X-RateLimit-*; X-Request-Id and traceparent echoed; an ETag on every GET, If-None-Match answered 304.
  • Discovery: /api/v1/openapi.json, /llms.txt and /llms-full.txt.
  • MCP: sign-in with OAuth 2.1 (MCP authorization spec 2025-11-25, PKCE S256, protected-resource metadata, server card at /.well-known/mcp.json), default scopes read search; outputSchema and structuredContent on every tool; enrol_in_sequence confirms in two steps.
  • Prospects gain a stage field, the pipeline stage the Partners screen shows.

1.0.0 — The first contract, read-only.

  • Four operations: the public program directory (GET /v1/programs, GET /v1/programs/{slug}), the calling account (GET /v1/me) and its commissions (GET /v1/commissions).
  • Bearer keys gaff_live_…, stored as a digest and shown once; a per-key rate limit by plan, with X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After.
  • Cursor pagination, browser origins refused (CORS), and an OpenAPI 3.1 document derived from the schemas the routes enforce.

  • The directory endpoints take their English path: /v1/programmes becomes /v1/programs.