# Photumo API — Agent Documentation

Base URL: `https://photumo.com`

All endpoints return JSON by default. Human-readable content pages additionally support markdown via `Accept: text/markdown` content negotiation.

## GET /api/health

Service health check.

```http
GET /api/health HTTP/1.1
Accept: application/json
```

```json
{ "status": "ok", "service": "photumo", "time": "2026-04-23T10:00:00Z" }
```

## GET /api/products

Full canvas catalog — sizes per format, current prices (EUR, 50% launch discount reflected in `price`), frame options.

```http
GET /api/products HTTP/1.1
Accept: application/json
```

```json
{
  "currency": "EUR",
  "discountPercent": 50,
  "formats": {
    "portrait":  [ { "id": "70x105", "dims": "70 × 105 cm", "price": 82.92, "originalPrice": 166, "popular": true } ],
    "landscape": [ { "id": "120x70", "dims": "120 × 70 cm", "price": 89.39, "originalPrice": 179, "popular": true } ],
    "square":    [ { "id": "80x80",  "dims": "80 × 80 cm",  "price": 95.31, "originalPrice": 191, "popular": true } ]
  },
  "frames": [
    { "id": "oak",   "label": "Oak frame",   "price": 120, "originalPrice": 240 },
    { "id": "black", "label": "Black frame", "price": 100, "originalPrice": 200 },
    { "id": "white", "label": "White frame", "price": 100, "originalPrice": 200 }
  ]
}
```

## POST /api/checkout

Create a Stripe Checkout session for a canvas order. Returns the Stripe URL to redirect the customer to.

```http
POST /api/checkout HTTP/1.1
Content-Type: application/json
```

```json
{
  "imageDataUrl": "data:image/jpeg;base64,/9j/4AAQSk...",
  "email": "buyer@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "address": "12 Byron St",
  "city": "London",
  "zip": "W1A 1AA",
  "country": "GB",
  "sizeId": "70x105",
  "sizeDims": "70 × 105 cm",
  "frameId": "oak",
  "frameLabel": "Oak frame",
  "totalEur": 202.92,
  "currency": "GBP"
}
```

Response:

```json
{ "url": "https://checkout.stripe.com/c/pay/cs_..." }
```

## Agent discovery

- API catalog: `/.well-known/api-catalog`
- OpenAPI: `/.well-known/openapi.json`
- MCP server card: `/.well-known/mcp/server-card.json`
- Agent skills: `/.well-known/agent-skills/index.json`

## Authentication

Public endpoints (`/api/health`, `/api/products`) require no authentication. The order endpoint (`/api/checkout`) is rate-limited but unauthenticated; the user authenticates to Stripe via the returned URL. See `/.well-known/oauth-protected-resource` for the resource metadata.