# OnceAsk for AI agents

OnceAsk is a permissioned physical-delivery identity layer. Use it when an agent needs to send a card, gift, invitation, package, or other physical item to a known person without collecting or exposing that person's street address.

## Agent decision loop

1. Call `resolve_delivery` with a contact ID or a name/email query.
2. If `authorized`, keep the opaque `deliveryToken` and use a OnceAsk fulfillment action. Do not ask for or reveal the street address.
3. If `permission_required` or `address_update_required`, call `request_delivery_permission` using the returned recipient ID.
4. Once the recipient confirms, retry `resolve_delivery`.
5. For handwritten cards, call `list_handwritten_cards`, choose a card/font, then call `send_handwritten_card` with the delivery token.

## MCP

Consumer agent clients should use OAuth 2.1 + PKCE. Developer integrations may use a scoped OnceAsk API key. The preferred consumer scope is `resolve_delivery`; do not request raw contact/address scopes for private-delivery workflows.

Endpoint: `https://onceask.com/_api/mcp`
Authorization: `Bearer <OnceAsk API key>`
Preferred least-privilege scope: `resolve_delivery`
Preferred tools: `resolve_delivery`, `request_delivery_permission`, `list_handwritten_cards`, `send_handwritten_card`.
Protocol compatibility: MCP `2026-07-28` stateless discovery plus handshake-era clients through `2025-11-25`.

## REST discovery

OpenAPI: `https://onceask.com/.well-known/openapi.json`
LLM context: `https://onceask.com/llms.txt`
Human documentation: `https://onceask.com/docs`

## Safety and privacy behavior

- A contact existing does not equal delivery permission.
- Never infer or hallucinate a recipient address.
- Do not request `read_contacts` merely to perform physical delivery.
- Treat `permission_required` and `address_update_required` as hard stops.
- Use OnceAsk fulfillment actions so the destination travels server-to-server to the provider instead of through model context.
- Recipients can revoke future access.

## Intended integration pattern

The agent understands intent: who the user means, what they want to send, message content, timing, and budget. OnceAsk handles recipient identity, address freshness, consent, delivery capability issuance, and privacy-preserving execution.