For developers

The REST API.

Call the same operations the app uses, over HTTPS, with an OAuth token for one gift group or your account.

Base URL

https://api.giftafari.com/v1

Send a bearer token on every call. A request that carries a Cookie header is refused with BEARER_REQUIRED, even when it also has a token, so call the API from a server or script rather than a signed-in browser. Responses use the envelope { data, error, meta }.

curl -H "Authorization: Bearer $TOKEN" \
  https://api.giftafari.com/v1/lists?groupId=$GROUP_ID

Every endpoint is in the generated OpenAPI document.

Get a token

A call without a token returns 401 with a WWW-Authenticate header that points to the protected-resource metadata. From there an OAuth 2.1 client registers itself at https://app.giftafari.com/api/oauth/register, then uses the authorization code flow with PKCE or the device flow, and asks for resource=https://api.giftafari.com/v1. The person approving picks one gift group (group scopes) or approves account access (account scopes); one token cannot hold both.

Writes and retries

Creating a person, list, gift, claim, or invitation, and duplicating a gift, requires an Idempotency-Key header of up to 200 characters; other writes accept one. Retrying with the same key and the same body replays the first result for 24 hours. The same key with a different body returns IDEMPOTENCY_CONFLICT, and a request still running returns IDEMPOTENCY_IN_PROGRESS. An uncertain result keeps its key for 30 days and returns IDEMPOTENCY_OUTCOME_UNKNOWN: check the resource before trying again with a new key. Versioned updates reject stale writes.

Approvals

Sensitive operations take two calls. First POST /v1/approvals {"operationId": "…", "arguments": {…}} returns an approvalToken and the consequences to show the person. Then call the operation with the same arguments plus approvalToken in the JSON body. The token works once, for five minutes, for exactly those arguments and that version. Without it the operation returns APPROVAL_REQUIRED.

Limits and errors

Every API response except the OpenAPI document and an OPTIONS preflight carries the IETF RateLimit and RateLimit-Policy headers, and a 429 adds Retry-After in seconds. Every 4xx and 5xx body is { data: null, error: { code, message }, meta }: branch on error.code. The developer portal lists the quotas and the common codes.

Scopes

Group scopes cover people, lists, gifts, claims, invitations, shares, and connections for one group. Account scopes cover profile, notifications, export, credential cleanup, membership discovery, and account closure.

Working from a terminal? The CLI wraps these endpoints. Connecting Claude or ChatGPT? Use MCP instead of calling the API yourself.