v1 · Stable
Giftopia API
JSON over HTTPS. All endpoints require a bearer token.
Base URL
https://api.giftopia.app
Authentication
curl -X POST https://api.giftopia.app/v1/auth/login \
-H "Content-Type: application/json" \
-d '{ "email": "ava@giftopia.app", "password": "•••" }'Response:
{ "token": "eyJhbGci…", "expires_in": 3600, "user": { "id": "usr_8x2", "name": "Ava" } }Endpoints
POST
/v1/auth/login
Exchange credentials for a session token
GET
/v1/recipients
List all recipients for the authenticated user
POST
/v1/recipients
Create a recipient
PATCH
/v1/recipients/:id
Update a recipient
DELETE
/v1/recipients/:id
Delete a recipient
GET
/v1/occasions
List occasions (filterable)
POST
/v1/occasions
Create an occasion
GET
/v1/gifts
List gift ideas
POST
/v1/gifts
Save a gift idea
POST
/v1/subscriptions/checkout
Create RevenueCat checkout session
Example · Create occasion
POST /v1/occasions
Authorization: Bearer eyJhbGci…
{
"title": "Mum's Birthday",
"date": "2026-03-14",
"recipient_id": "rec_8x2",
"budget": 120,
"type": "Birthday"
}Response · 201 Created
{ "id": "occ_J2K", "status": "upcoming", "reminders": ["−14d","−7d","−1d"] }Error handling
{ "error": { "code": "validation_error", "message": "date must be in the future", "field": "date" } }400 · Validation
401 · Unauthenticated
403 · Forbidden
404 · Not found
429 · Rate limit
500 · Server error
Webhooks
Subscribe to events at /v1/webhooks:
occasion.created occasion.reminder.sent gift.purchased subscription.activated subscription.cancelled
Lifecycle
Request
→Auth
→Validate
→Handle
→Persist
→Respond