# Thinking of U — Physical Goods API for AI Agents

> Thinking of U provides an API that lets AI agents send physical items — starting with printed postcards — to real people via mail. Agents provide a message and image, we print and mail it. Pay per request via Stripe MPP or API key.

The Thinking of U Gateway API is a fulfillment service for AI agents that need to interact with the physical world. You provide the content, we handle printing, postage, and delivery.

Currently available services:

- **Physical Postcard**: Send a 4x6 printed postcard via USPS. Provide a message (up to 350 characters) and a front image URL. We validate the address, moderate content, print, and mail it. $5 per card. Delivery: 5-7 business days in the US.

## API Endpoints

- [Service Discovery — GET /v1/services](https://us-central1-thinking-of-u-prod.cloudfunctions.net/gateway/v1/services): List all available services with pricing, schemas, and descriptions. No authentication required.
- [Create Order — POST /v1/services/postcard/orders](https://us-central1-thinking-of-u-prod.cloudfunctions.net/gateway/v1/services/postcard): Send a postcard. Requires API key (Bearer token) or Stripe MPP payment. Returns order ID for status tracking.
- [Validate Address — POST /v1/services/postcard/validate](https://us-central1-thinking-of-u-prod.cloudfunctions.net/gateway/v1/services/postcard): Pre-flight address validation before ordering.
- [Order Status — GET /v1/services/postcard/orders/{id}](https://us-central1-thinking-of-u-prod.cloudfunctions.net/gateway/v1/services/postcard): Check order status and get PDF/tracking when complete.
- [MCP Server — POST /v1/mcp](https://us-central1-thinking-of-u-prod.cloudfunctions.net/gateway/v1/mcp): Model Context Protocol endpoint for AI agent tool discovery and use.

## Postcard API Input

To send a postcard, POST JSON with these fields:

- `recipientName` (string, required): Full name of the recipient.
- `recipientAddress` (object, required): `{ street, city, postalCode, country }`. Country defaults to "US".
- `message` (string, required): Text for the back of the postcard. Max 350 characters.
- `frontImageUrl` (string, required): Publicly accessible URL for the front image. 1024x1024px recommended.
- `senderName` (string, required): Name of the sender.
- `idempotencyKey` (string, optional): Prevents duplicate orders.

## Authentication

Two methods:

1. **API Key**: Include `Authorization: Bearer tou_live_...` header. Contact us for a key.
2. **Stripe MPP**: No key needed. Send request without auth, receive HTTP 402 with payment challenge, complete payment, retry with receipt.

## MCP Tools

Agents connecting via Model Context Protocol get these tools:

- `list_services` — Discover available services and pricing
- `send_postcard` — Create and mail a postcard
- `validate_postcard` — Check address validity before ordering
- `check_order_status` — Track an order by ID

## Optional

- [Terms of Service](https://thinking-of-u.com/terms-of-service): Legal terms for API usage.
- [Privacy Policy](https://thinking-of-u.com/privacy-policy): How we handle data.
- [Contact](https://thinking-of-u.com/contact-us): Reach the team for API key requests or questions.