Public API & Zapier

A REST API for reading your guild's data and creating members, plus signed outbound webhooks that fire on member, payment, registration and form events. Base URL https://quilthosting.com/api/v1.

API keys and scopes

Admin → API (owners and admins). Create a key, tick the scopes it needs, and copy it — it is shown once. Keys look like qh_…; only a hash is stored. Revoke a key from the same screen; the last-used time is recorded.

ScopeGrants
readAlways granted. All GET endpoints.
members:writePOST /members, PATCH /members/:id
hooks:writePOST /hooks, DELETE /hooks/:id

A trigger-only Zap needs hooks:write (Zapier subscribes and unsubscribes when the Zap is switched on and off) but not members:write. Keys created before v0.27 may carry a legacy write scope that grants both.

Authentication

Authorization: Bearer qh_…your_key…

Or, less securely, ?api_key=qh_…. API routes are exempt from the private-preview site password; the key is the only gate. An inactive guild returns 403.

Never commit keys to git or paste them into shared Zaps. Revoke a leaked key immediately.

Read endpoints

MethodPathReturns
GET/meTenant id, name, slug, plan, and the key's scopes
GET/members?status=&limit=&offset=&page=Paginated: {members, total, limit, offset, page, total_pages, has_more}. Default 100 per page, max 500.
GET/eventsUp to 200 events (no pagination)
GET/paymentsUp to 200 payments (no pagination)
GET/levelsActive membership levels
GET/hooksUp to 100 hook subscriptions (secrets never returned)
curl -s "https://quilthosting.com/api/v1/members?status=active&limit=200" \
  -H "Authorization: Bearer qh_…"

Member object fields: id, email, first_name, last_name, phone, status, joined_at, created_at.

Write endpoints

POST /members — members:write

curl -s -X POST https://quilthosting.com/api/v1/members \
  -H "Authorization: Bearer qh_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: zap-01H8XYZ" \
  -d '{"email":"member@example.com","first_name":"Ada","status":"pending"}'

Body: email (required), first_name, last_name, phone, status (pending | active | lapsed | cancelled; default pending). Returns 201 {"member": {…}}. Creating with active uses a slot against the free plan's 30-active-member limit (402 plan_limit when full). A duplicate email returns 409 duplicate_email with the existing member_id.

PATCH /members/:memberId — members:write

Body: any of first_name, last_name, phone, status. Email cannot be changed here — a mistyped Zap would silently split a member's history in two. Change email in the admin.

Idempotency-Key

Accepted on POST /members and PATCH /members/:id only. Strongly recommended on create: Zapier and Make retry on timeout, and without a key a retried create hits the duplicate-email guard and reports failure for a member that was in fact created.

  • Same key, same body → the original response is replayed (kept for about 24 hours, worst case about 48).
  • Same key, different body (or a different memberId) → 422 idempotency_key_reuse.
  • Same key while the first request is still running → 409 idempotency_in_progress with Retry-After: 2. Wait and retry; this is not an error.
  • 402 and 5xx responses are not cached, so a retry after the condition clears runs for real.
  • The key is scoped per operation, so reusing one id for a create and a later update of the same member is safe.

This is a 60-second concurrency guard, not an end-to-end exactly-once guarantee; details in the repo's docs/api.md.

REST hooks

POST /hooks — hooks:write

curl -s -X POST https://quilthosting.com/api/v1/hooks \
  -H "Authorization: Bearer qh_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.zapier.com/…","events":["member.created"]}'

Returns 201 {"hook": {"id","url","events","secret"}} — the secret is shown once. URLs must be https and not point at private networks or QuiltHosting itself. Unknown event names are rejected with 400 unknown_event, never silently dropped. Omitting events subscribes to everything (*). Limit 25 hooks per guild (429 hook_limit).

DELETE /hooks/:hookId — hooks:write

Returns 200 {"deleted": true}.

Outbound webhooks

Hooks (and endpoints added under Admin → Zapier) receive a POST for each event:

EventWhen
member.createdA member record is created (admin, join form, or API — not CSV import)
member.activatedA member becomes active
member.updatedA member's details or status change (carries previous_status and status)
membership.activatedA membership becomes active, with level details
payment.succeededA checkout completes
event.registrationSomeone takes an event seat (free, waitlist or paid)
form.responseA public form is submitted
{
  "id": "delivery-uuid",
  "schema_version": 1,
  "event": "member.activated",
  "created_at": "2026-09-08T12:00:00.000Z",
  "tenant_id": "…",
  "data": { "source": "join_form", "member_id": "…", "email": "…", "level_id": "…" }
}

Headers: X-QH-Event, X-QH-Delivery ({outbox-id}:{endpoint-id}, constant across retries of the same delivery), X-QH-Timestamp (unix seconds), X-QH-Schema-Version, and X-QH-Signature = HMAC-SHA256 hex of {timestamp}.{raw body} using the hook secret. Verify the signature, reject timestamps older than five minutes, and dedupe on id — delivery is at-least-once.

A 2xx response counts as delivered. Anything else is retried up to 6 attempts with jittered backoff (roughly 2.5–5 min, 12–25 min, 1–2 h, then 5–10 h), after which the event is marked dead. An endpoint that fails 20 times in a row is switched off; Admin → Zapier shows an auto-disabled badge with a Re-enable button, a Recent deliveries list with status, attempts and last error, and Replay for failed or dead events. Test sends a test.ping directly (it does not carry X-QH-Delivery).

Zapier and Make

  1. Admin → API → create a key with the scopes you need and copy it.
  2. In Zapier, create a Zap with Webhooks by Zapier → Catch Hook and copy its URL.
  3. Either paste the URL under Admin → Zapier → Add endpoint (choose events, save the signing secret shown once, click Test), or subscribe it with POST /hooks.
  4. For actions, use Webhooks by Zapier → Custom Request against POST /members with an Idempotency-Key such as the Zap's task id.

There is also a native Zapier app (private, not listed in the Zapier directory) with New Member and New Event Registration triggers and a Create Member action. Polling /members or /payments on a schedule and filtering by created_at also works.

Error codes

Errors are {"error": "message", "code": "…"}.

CodeStatusMeaning
(none)401Missing or invalid API key
missing_field400A required field was absent
invalid_status400Status not in the allowed list (valid array included)
no_fields400PATCH body had nothing to change
unknown_event400Event name not in the catalog (valid array included)
invalid_hook_url400Not https, or a blocked host
plan_limit402Free plan active-member limit reached
insufficient_scope403Key lacks the required scope (required included)
not_found404No such member or hook in this guild
duplicate_email409A member already uses that email (member_id included)
idempotency_in_progress409Same key still executing; retry after Retry-After
idempotency_key_reuse422Key reused with a different body
hook_limit42925 hooks per guild reached
event_prepare_failed500The webhook event could not be prepared; nothing was written

Limits and notes

  • No per-key rate limit is enforced today. Be a good citizen; poll no more often than every few minutes.
  • /events and /payments return at most 200 rows; /members is paginated (offset-based, offsets capped at 100,000).
  • Versioning is by URL path (/api/v1); webhook payloads carry their own schema_version.
  • CSV imports do not fire member.created; poll /members after an import.
  • The admin and portal use their own sign-in sessions, not API keys. The CSV importer is an admin route, not part of the API.
  • Full contract for developers: docs/api.md and docs/zapier-webhooks.md in the repository.