# Wish List Agent Action Guide

This guide describes the preferred API flow for agents acting on behalf of a Wish List user.

## Discovery

Use `/openapi.json` as the source of truth for request bodies, response schemas, status codes, and authentication.

Useful discovery resources:

1. `/llms.txt`.
2. `/llms-full.txt`.
3. `/agents.txt`.
4. `/.well-known/ai`.
5. `/.well-known/ai-catalog.json`.
6. `/.well-known/api-catalog`.
7. `/.well-known/oauth-authorization-server`.
8. `/.well-known/oauth-protected-resource`.

## Authentication

Authenticated actions use OAuth2 Bearer access tokens.

Use authorization code with PKCE for agents and third party applications:

1. Discover metadata at `/.well-known/oauth-authorization-server`.
2. Register an OAuth client at `/o/register/` when Dynamic Client Registration is enabled.
3. Redirect the user to `/o/authorize/` with `response_type=code`, `state`, `code_challenge`, and `code_challenge_method=S256`.
4. Let the user sign in and approve the Wish List consent screen.
5. Exchange the returned code at `/o/token/` with the PKCE `code_verifier`.

Send authenticated API requests with this header:

```http
Authorization: Bearer <access_token>
```

Wish List exposes OAuth2 discovery metadata, but does not publish OpenID Connect discovery metadata.
OAuth tokens enforce `read` for safe methods and `write` for mutating methods.

## Recommended Flows

### Create a wish list item

1. Authenticate the user.
2. Retrieve the current user profile with `GET /api/me/profile/`.
3. Retrieve the user's wish lists with `GET /api/me/wishlists/`.
4. Create an item with `POST /api/me/wishlists/{wishlist_id}/items/`.
5. Use `/api/media/images/` first when the item needs an uploaded image.

### Create an event

1. Authenticate the user.
2. Create the event with `POST /api/me/events/`.
3. Link visible wish items with `wish_item_ids` when useful.
4. Add organizers through `/api/me/events/{event_id}/organizers/` only when the user explicitly asks.

### Reserve a gift

1. Authenticate the user.
2. Retrieve visible events, wish lists, or wish items through the public user endpoints.
3. Reserve only after explicit user confirmation.
4. Treat `403` and `404` responses as access denied or unavailable content.

## Safety Rules

1. Ask before creating, updating, deleting, reserving, notifying, or sending invitations.
2. Do not infer hidden profile fields from omitted data.
3. Do not retry destructive actions automatically.
4. Respect profile, content, event, and friendship visibility rules.
5. Use OpenAPI schemas rather than scraping frontend pages.