---
title: "Request gift ideas"
method: POST
path: "/api/gift/{token}/recommend"
tags: ["gifts"]
---

# Request gift ideas

`POST /api/gift/{token}/recommend`

## Request

- Base URL: `https://leafle.org` (the document declares no server; this is the origin it was published from)
- URL: `https://leafle.org/api/gift/{token}/recommend`
- Auth: none required

**Access: signed link.** The token in the path is the credential.

Generate gift ideas from the frozen gift card and giver's request. This consumes a use of the link. Reopening the link retrieves earlier ideas without spending another use. An exhausted, invalid, expired or revoked link returns 410.

## Path parameters

- `token` string, required

## Request body

- GiftAskBody
  - `occasion` string
  - `budget` string
  - `format` string
  - `vibe` string

## Response `200`

Successful Response

- GiftRecommendation: One generation of gift ideas. A detail field reports failure after the response started; inspect it even on HTTP 200. It is absent on success.
  - `picks` GiftPick[], required
    - `title` string, nullable
    - `author` string, nullable
    - `why_this_gift` string, nullable
    - `buy_url` string, nullable
    - `isbn` string, nullable
    - `year` union
      - integer
      - string
    - `cover_url` string, nullable
    - `review_url` string, nullable
  - `label` string, required
  - `detail` string, nullable

## Other responses

- `410`: This link is no longer available.
- `422`: Validation Error
- `429`: Request or usage limit reached. Wait before retrying.
- `503`: Capacity is unavailable or the service is restarting. Honour Retry-After when present.

---

[API](https://skmtc.dev/leafle/apis/leafle-api.md) · [All operations](https://skmtc.dev/leafle/apis/leafle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/leafle/apis/leafle-api/revisions/f2e56cb74495?raw)