# StableDesign API

> Canva design creation, listing, and export — powered by MPP micropayments on Tempo.

## Base URL

https://stabledesign.vercel.app

## Payment

All paid endpoints use the Machine Payments Protocol (MPP) on the Tempo blockchain.
Currency: pathUSD (USDC equivalent on Tempo)
When you call a paid endpoint without payment, you'll receive HTTP 402 with a payment challenge.
Use an MPP-compatible client (e.g. `mppx` CLI or SDK) to handle payment automatically.

## Endpoints

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | /api/health | free | Health check |
| GET | /llms.txt | free | This documentation |
| GET | /api/oauth/authorize | free | Start Canva OAuth flow (browser) |
| POST | /api/designs/create | $0.01 | Create a new Canva design |
| POST | /api/designs/get | $0.01 | Get design details by ID |
| GET | /api/designs/list | $0.01 | List user's designs |
| POST | /api/designs/export | $0.02 | Export a design to PNG/PDF/JPG |
| POST | /api/assets/upload | $0.01 | Upload an image/video asset by URL |
| GET | /api/user | free | Get authenticated Canva user info |

## Authentication

This API requires a one-time Canva OAuth setup:
1. Visit /api/oauth/authorize in a browser
2. Authorize the StableDesign integration
3. The server stores the token — all subsequent API calls use it automatically

## POST /api/designs/create

Create a new Canva design.

Request body (JSON):
- preset (string, optional): "doc" | "email" | "presentation" | "whiteboard"
- asset_id (string, optional): Image asset ID to insert into the design
- title (string, optional): Design title (1-255 chars)
- width (number, optional): Custom width in px (40-8000), use with height for custom dimensions
- height (number, optional): Custom height in px (40-8000), use with width for custom dimensions

Provide at least one of: preset, asset_id, or width+height.

Example:
```
curl -X POST https://stabledesign.vercel.app/api/designs/create \
  -H "Content-Type: application/json" \
  -d '{"preset": "presentation", "title": "Q4 Report"}'
```

Response: Canva design object with id, title, edit URL, view URL.

## GET /api/designs/list

List the authenticated user's designs.

Query parameters:
- ownership (string, optional): "owned" | "shared" | "any" (default: "owned")
- sort_by (string, optional): "relevance" | "modified_descending" | "modified_ascending" | "title_descending" | "title_ascending"
- continuation (string, optional): Pagination token from previous response

Example:
```
curl https://stabledesign.vercel.app/api/designs/list?ownership=owned&sort_by=modified_descending
```

Response: Array of design objects with pagination continuation token.

## POST /api/designs/export

Export a Canva design to a downloadable file format.

Request body (JSON):
- design_id (string, required): The Canva design ID to export
- format (object, required):
  - type (string): "pdf" | "jpg" | "png" | "gif" | "pptx" | "mp4"
  - quality (number, optional): 1-100, for JPG only
  - lossless (boolean, optional): for PNG only

IMPORTANT: Not all formats work with all design types. Use PDF as the safe default.
- doc → pdf only
- presentation → pdf, pptx, png, jpg
- email → pdf, png, jpg
- whiteboard → pdf, png, jpg
- custom (width+height) → pdf, png, jpg, gif
Requesting an unsupported format returns 400.

Example:
```
curl -X POST https://stabledesign.vercel.app/api/designs/export \
  -H "Content-Type: application/json" \
  -d '{"design_id": "DAGabc123", "format": {"type": "pdf"}}'
```

Response: Export job with status and download URL (when complete).

## POST /api/designs/get

Get details for a specific design.

Request body (JSON):
- design_id (string, required): The Canva design ID

Example:
```
curl -X POST https://stabledesign.vercel.app/api/designs/get \
  -H "Content-Type: application/json" \
  -d '{"design_id": "DAHI0X3WEAY"}'
```

Response: Design object with id, title, owner, edit/view URLs, thumbnail, page count.

## POST /api/assets/upload

Upload an image or video to Canva by URL.

Request body (JSON):
- name (string, required): Asset name (1-50 chars)
- url (string, required): Public URL of the image/video to upload

Supported: JPEG, PNG, GIF, WebP, HEIC, TIFF (max 50MB), MP4, WebM, MKV (max 500MB)

Example:
```
curl -X POST https://stabledesign.vercel.app/api/assets/upload \
  -H "Content-Type: application/json" \
  -d '{"name": "Hero Image", "url": "https://example.com/photo.jpg"}'
```

Response: Asset upload job with status and asset details (when complete).

## GET /api/user

Get the authenticated Canva user profile. Free (no payment required).

Example:
```
curl https://stabledesign.vercel.app/api/user
```

Response: User object with user_id and team_id.

## Notes

- Blank designs auto-delete after 7 days if not edited in Canva
- Export download URLs are valid for 24 hours
- Canva rate limits: ~20 requests/minute per user for most operations
- Export and upload are async — the API polls automatically (up to 30s for export, 15s for upload) before returning
- All paid endpoints charge on request, even if the Canva operation fails (e.g. invalid design_id, unsupported format). Validate inputs before calling.