GiftIdeasAI API

Manage people, occasions, gift lists and gift plans, and find gift ideas, from your own scripts and tools.

The GiftIdeasAI API gives scripts, automations and AI agents the same gift planning you do in the app: the people you buy for, their occasions, your gift lists and wishlists, the gifts you plan to give, and the gifts someone received. It can also suggest gift ideas.

Base URL: https://giftideasai.com/api/v1
Interactive reference: giftideasai.com/api/v1/docs, with every endpoint, schema and a request console
OpenAPI document: giftideasai.com/api/v1/openapi.json
AI assistants: connect Claude, ChatGPT or Cursor through the MCP server instead; it needs no key.

Get an API key

Sign in and open Settings → Gift space → Agents & API.
Under API keys, give the key a name and pick when it expires.
Copy the key. It starts with gia_ and is shown once; if you lose it, revoke it and create a new one.

Only owners and admins of a gift space can create keys. A key works in that one gift space, with the permissions of the person who created it: a viewer's role can read but not change anything. If its creator leaves the gift space, the key stops working.

Authenticate

Send the key in the x-api-key header:

curl https://giftideasai.com/api/v1/people \
  -H "x-api-key: gia_your_key"

The API accepts API keys only; browser sessions don't work on /api/v1.

What you can do

Area	Endpoints
Gift space	`GET /gift-space`
People	`GET /people`, `POST /people`, `PATCH /people/{id}`, `DELETE /people/{id}`, `POST /people/archive`
Occasions	`GET /occasions`, `POST /occasions`, `PATCH /occasions/{id}`, `DELETE /occasions/{id}`, `POST /occasions/archive`, `GET /occasion-occurrences`
Gift lists	`GET /gift-lists`, `POST /gift-lists`, `PATCH /gift-lists/{id}`, `DELETE /gift-lists/{id}`, `POST /gift-lists/archive`
Gift items	`GET /gift-items`, `POST /gift-items`, `PATCH /gift-items/{id}`, `DELETE /gift-items/{id}`
Gift plans	`GET /gift-plans`, `POST /gift-plans`, `PATCH /gift-plans/{id}`, `POST /gift-plans/{id}/status`, `POST /gift-plans/status`, `DELETE /gift-plans/{id}`, `POST /gift-plans/archive`
Received gifts	`GET /received-gifts`, `POST /received-gifts`, `PATCH /received-gifts/{id}`, `DELETE /received-gifts/{id}`, `POST /received-gifts/archive`
Gift ideas	`POST /gift-ideas`, `GET /gift-ideas/amazon-product`

A few things work the same everywhere:

Updates are partial. A PATCH changes only the fields you send. Sending recipientIds replaces the set of people.
DELETE archives. Archived records disappear from GiftIdeasAI; bulk .../archive endpoints take up to 100 ids.
Dates are ISO strings, such as 2026-12-24.
Reservations stay private. Who reserved or bought which wishlist item is never returned, so the API can't spoil a surprise.

Example: add a birthday and a gift idea

# Add a person
curl -X POST https://giftideasai.com/api/v1/people \
  -H "x-api-key: gia_your_key" -H "content-type: application/json" \
  -d '{"displayName": "Mom", "relationship": "parent", "birthdayMonth": 5, "birthdayDay": 12}'

# Her birthday, every year
curl -X POST https://giftideasai.com/api/v1/occasions \
  -H "x-api-key: gia_your_key" -H "content-type: application/json" \
  -d '{"title": "Mom’s birthday", "startsAt": "2027-05-12", "repeats": "yearly", "recipientIds": ["grc_..."]}'

# Ask for ideas
curl -X POST https://giftideasai.com/api/v1/gift-ideas \
  -H "x-api-key: gia_your_key" -H "content-type: application/json" \
  -d '{"relationship": "Mother", "interests": ["gardening", "tea"], "priceRanges": "$25-$50"}'

Gift ideas and Amazon links

POST /gift-ideas suggests up to nine ideas from an optional description of the person: relationship, age range, interests, budget, occasion and gift type. Each idea comes with an Amazon search link. Nothing is saved; add the ideas you like with POST /gift-items or POST /gift-plans.

GET /gift-ideas/amazon-product?title=... returns an Amazon link for a gift: the matching product page when one is found in time, otherwise an Amazon search. Both return the title and the link only. As an Amazon Associate, GiftIdeasAI earns from qualifying purchases through these links.

Limits

What	Limit
Requests per API key	300 per 15 minutes
Gift idea searches	50 per day per gift space, and 50 per day per key
Amazon lookups	500 per day per gift space, and 500 per day per key

Daily limits reset at midnight UTC. A request over a limit gets 429 with a Retry-After header in seconds.

Errors

Errors are JSON with a code, the HTTP status and a readable message:

{ "defined": true, "code": "NOT_FOUND", "status": 404, "message": "Person not found" }

Status	Meaning
400	The input failed validation; `data.issues` says which field.
401	Missing or invalid API key.
403	Your role doesn't allow this, or the key's creator left the gift space.
404	The record doesn't exist in this gift space, or the endpoint isn't part of the API.
429	A limit was reached; wait for `Retry-After` seconds.

Not available

Reservations, uploads (avatars, receipts), onboarding, member invites and roles, gift space settings and deletion, and API key management stay in the app.

Revoke a key

Open Settings → Gift space → Agents & API and revoke the key. Anything using it stops working right away.