Agentic-first

GiftShopper for Agents

Your agent already knows your calendar, your contacts, and your tone of voice. Give it the missing piece: a memory of the people you give gifts to, a recommender that gets smarter every search, and shoppable links it can hand you to close the loop.

Create an API key OpenAPI spec

Free + unlimited generation

Generating gift ideas is free, same as the website. Shoppable-link lookups are fair-use capped at 200/day per key.

Scoped per user

Each key resolves to a specific account. Agents can't see other users' people.

Revoke any time

Manage keys, see recent activity, and kill access in one click.

01Connect

MCP — Claude, Cursor, ChatGPT

Drop this into your MCP client config. It exposes list_people, generate_gifts, save_favorite, and more as native tools.

mcp-config.json

{
  "mcpServers": {
    "giftshopper": {
      "url": "https://xukplfujaizlcbmdzstn.supabase.co/functions/v1/mcp",
      "headers": { "Authorization": "Bearer gs_live_YOUR_KEY" }
    }
  }
}

02Try it

REST quickstart

Create a person

curl

curl -X POST https://xukplfujaizlcbmdzstn.supabase.co/functions/v1/agent-api/people \
  -H "Authorization: Bearer gs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mom",
    "relationship": "Mother",
    "age_range": "Senior (60+)",
    "gender": "Female",
    "notes": "Loves gardening, reads mysteries, hates clutter"
  }'

Generate gifts (free + unlimited)

curl

curl -X POST https://xukplfujaizlcbmdzstn.supabase.co/functions/v1/agent-api/gifts/generate \
  -H "Authorization: Bearer gs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "the-person-uuid",
    "occasion": "Birthday",
    "budget": "$50-$100"
  }'

Resolve a shoppable URL

curl

curl -X POST https://xukplfujaizlcbmdzstn.supabase.co/functions/v1/agent-api/gifts/shop-url \
  -H "Authorization: Bearer gs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Hori Hori garden knife", "source": "amazon" }'

03Capabilities

What agents can do

List, create, and update saved people

Add recurring occasions

Generate personalized gift ideas

Resolve real Amazon / Google Shopping links

Save favorites and record purchases

Check account and subscription state

Out of scope for v1: programmatic checkout. Agents return shoppable links; the human completes purchase at the merchant.

04Multi-user

OAuth 2.1

Building an agent that serves many users? Register an OAuth app and use the authorization code + PKCE flow. Users see a consent screen, can revoke at any time from /settings/connected-apps, and access tokens expire after 1 hour (use the refresh token to rotate).

Redirect the user to authorize

Build the authorization URL with your client ID, PKCE code challenge, and desired scopes.

authorize

GET /functions/v1/agent-oauth/authorize
  ?client_id=gs_app_...
  &redirect_uri=https://yourapp.com/oauth/callback
  &response_type=code
  &code_challenge=<S256(verifier)>
  &code_challenge_method=S256
  &scope=people:read+gifts:generate
  &state=<random>

Handle the callback

After the user consents, we redirect back to your redirect_uri with ?code=...&state=.... Validate state, then exchange the code.

Exchange code for tokens

Send the authorization code, original code verifier, and client credentials to receive tokens.

token request

POST /functions/v1/agent-oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "gs_code_...",
  "code_verifier": "...",
  "redirect_uri": "https://yourapp.com/oauth/callback",
  "client_id": "gs_app_...",
  "client_secret": "gs_cs_..."
}

# -> { access_token, refresh_token, expires_in, scope }

Call the API as the user

Use the access token for all subsequent API calls on behalf of the user.

authenticated request

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://xukplfujaizlcbmdzstn.supabase.co/functions/v1/agent-api/people

Ready to connect?

Start with a personal API key for solo agents, or register an OAuth app if you're building for multiple users.

Personal API key OAuth app