Build on Giftafari.

Free and self-serve

Giftafari is free, and so is the API. There is no sales call, waitlist, or key to request. Any script or agent registers its own OAuth client, then a person approves it for one gift group or for their account. Approval is the only human step.

Base URL: https://api.giftafari.com/v1
OpenAPI 3.1: https://api.giftafari.com/v1/openapi.json
MCP server: https://mcp.giftafari.com
Agent guide: https://www.giftafari.com/llms.txt

Quickstart

1. Register a public client (RFC 7591). The response holds your client_id.

curl -X POST https://app.giftafari.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "My gift script", "redirect_uris": ["http://127.0.0.1:8976/callback"]}'

2. Start the device flow (RFC 8628). Open verification_uri_complete, sign in, and pick the group to share. Approve only a code you started yourself: the app shows the client name the client chose, not a verified publisher.

curl -X POST https://app.giftafari.com/api/oauth/device_authorization \
  -d client_id=$CLIENT_ID \
  -d "scope=lists:read gifts:read" \
  -d resource=https://api.giftafari.com/v1

3. Poll for the token every interval seconds. Until the person approves, the token endpoint answers authorization_pending. A poll that comes too soon answers slow_down: wait 5 more seconds between polls.

curl -X POST https://app.giftafari.com/api/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=$CLIENT_ID \
  -d device_code=$DEVICE_CODE

4. Call the API with the access_token. A group token works on its own group, so groupId is optional.

curl -i -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.giftafari.com/v1/lists

Building a web app instead? Send the person to https://app.giftafari.com/oauth/authorize with response_type=code, your client_id and a registered redirect_uri, a scope of group scopes or account scopes (never both), a 43-character code_challenge with code_challenge_method=S256, and resource=https://api.giftafari.com/v1. The REST API guide covers scopes, idempotent writes, and approvals.

Credentials

Giftafari issues OAuth tokens instead of static API keys. A token covers one gift group (group scopes) or your account (account scopes), never both. Access tokens last an hour; trade the refresh_token for a new pair at the token endpoint.

To disconnect a client from a group, open the group’s AI agents page in the app: that ends the connection and every token under it. https://app.giftafari.com/api/oauth/revoke (RFC 7009) revokes one token, so send it the refresh token and the access token.

Test with a second account

Sign up a second, free Giftafari account for testing and approve your client for that account’s group. A group token cannot read or change any other group, so test lists, gifts, and claims stay away from the ones your family uses. Close the test account from its settings when you are done.

Rate limits

Each operation allows 120 requests per minute per client IP address, and POST /v1/approvals allows 30. Product previews stop at 60 a clock hour with PREVIEW_LIMIT. Every response under https://api.giftafari.com/v1 except the OpenAPI document and an OPTIONS preflight reports its window in the IETF RateLimit and RateLimit-Policy headers, usually named after the operation, plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset in seconds:

RateLimit-Policy: "lists.list";q=120;w=60
RateLimit: "lists.list";r=119;t=60
RateLimit-Limit: 120
RateLimit-Remaining: 119
RateLimit-Reset: 60

A refused call answers 429 with Retry-After in seconds. Wait that long, then retry. Counts are kept per server instance, so read the headers on each response rather than counting calls yourself.

The OAuth endpoints have their own limits per IP address: client registration 20 an hour, device authorization 20 a minute, and token and revoke 60 a minute. Register a client once and reuse its client_id.

Errors

Every 4xx and 5xx response under https://api.giftafari.com/v1 has the same body. Branch on error.code and show error.message to a person. The OpenAPI document types it as ErrorEnvelope on every operation. The OAuth endpoints answer in the standard OAuth shape instead: error and error_description.

{
  "data": null,
  "error": { "code": "INVALID_ID", "message": "listId must be a valid id" },
  "meta": { "requestId": "4f1c…" }
}

Common codes: INVALID_INPUT and INVALID_ID (400), BEARER_REQUIRED and INVALID_TOKEN (401), INSUFFICIENT_SCOPE (403), NOT_FOUND (404), VERSION_CONFLICT and APPROVAL_REQUIRED (409), RATE_LIMITED (429), and INTERNAL_ERROR (500). Quote meta.requestId when you contact us.

More tools

Connecting Claude or ChatGPT? Follow MCP for your AI. Scripting from a terminal? Read the CLI guide. What changed lately is in the changelog.