# StableDesign API

> Full Canva Connect API behind micropayments — designs, assets, brand templates, folders, comments, and more.

## Base URL

https://stabledesign.vercel.app

## Payment

This API accepts both **x402** (USDC on Base) and **MPP** (USDC on Tempo) micropayments.

When you call a paid endpoint without payment, you'll receive HTTP 402 with a payment challenge.
Use an x402-compatible client or MPP-compatible client to handle payment automatically.

### Agent Workflow (Progressive)

1. Discover endpoints: `mcp__agentcash__discover_api_endpoints("https://stabledesign.vercel.app")`
2. Check schema: `mcp__agentcash__check_endpoint_schema` before first fetch
3. Execute: `mcp__agentcash__fetch` with payment

## Authentication

All paid endpoints require 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

## Endpoints

| Method | Path | Price | Description |
|--------|------|-------|-------------|
| GET | /api/health | free | Health check |
| GET | /api/oauth/authorize | free | Start Canva OAuth flow (browser) |
| GET | /api/oauth/callback | free | Canva OAuth callback |
| GET | /api/user | free | Get authenticated Canva user info |
| POST | /api/designs/create | $0.01 | Create a new Canva design |
| POST | /api/designs/get | $0.01 | Get design details by ID |
| POST | /api/designs/list | $0.01 | List user's designs |
| POST | /api/designs/pages | $0.01 | Get pages of a design |
| POST | /api/designs/export-formats | $0.01 | Get available export formats |
| POST | /api/designs/export | $0.02 | Export a design to file |
| POST | /api/assets/upload | $0.01 | Upload an asset by URL |
| POST | /api/assets/get | $0.01 | Get asset details |
| POST | /api/assets/update | $0.01 | Update an asset (rename/re-tag) |
| POST | /api/assets/delete | $0.01 | Delete an asset |
| POST | /api/brand-templates/list | $0.01 | List brand templates |
| POST | /api/brand-templates/get | $0.01 | Get brand template details |
| POST | /api/brand-templates/dataset | $0.01 | Get template data fields |
| POST | /api/autofill/create | $0.02 | Autofill a brand template |
| POST | /api/autofill/status | $0.01 | Check autofill job status |
| POST | /api/imports/create | $0.02 | Import a design from URL |
| POST | /api/imports/status | $0.01 | Check import job status |
| POST | /api/resize/create | $0.02 | Resize a design |
| POST | /api/resize/status | $0.01 | Check resize job status |
| POST | /api/folders/create | $0.01 | Create a folder |
| POST | /api/folders/get | $0.01 | Get folder details |
| POST | /api/folders/update | $0.01 | Rename a folder |
| POST | /api/folders/delete | $0.01 | Delete a folder |
| POST | /api/folders/items | $0.01 | List folder contents |
| POST | /api/folders/move | $0.01 | Move items between folders |
| POST | /api/comments/create | $0.01 | Add a comment to a design |
| POST | /api/comments/get | $0.01 | Get a comment thread |
| POST | /api/comments/reply | $0.01 | Reply to a comment |
| POST | /api/comments/list-replies | $0.01 | List replies in a thread |

## Designs

### POST /api/designs/create ($0.01)
Create a new Canva design.
- preset (string, optional): "doc" | "email" | "presentation" | "whiteboard"
- asset_id (string, optional): Image asset ID to insert
- title (string, optional): Design title (1-255 chars)
- width/height (number, optional): Custom dimensions in px (40-8000)

### POST /api/designs/list ($0.01)
List designs. Body: { ownership?, sort_by?, continuation? }

### POST /api/designs/get ($0.01)
Get design details. Body: { design_id }

### POST /api/designs/pages ($0.01)
Get pages of a design. Body: { design_id }

### POST /api/designs/export-formats ($0.01)
Get available export formats. Body: { design_id }

### POST /api/designs/export ($0.02)
Export to PDF/JPG/PNG/GIF/PPTX/MP4. Body: { design_id, format: { type, quality?, lossless? } }. Async with polling.

## Assets

### POST /api/assets/upload ($0.01)
Upload by URL. Body: { name, url }. Async with polling.

### POST /api/assets/get ($0.01)
Get asset details. Body: { asset_id }

### POST /api/assets/update ($0.01)
Update asset. Body: { asset_id, name?, tags? }

### POST /api/assets/delete ($0.01)
Delete asset. Body: { asset_id }

## Brand Templates

### POST /api/brand-templates/list ($0.01)
List templates. Body: { query?, continuation? }

### POST /api/brand-templates/get ($0.01)
Get template details. Body: { brand_template_id }

### POST /api/brand-templates/dataset ($0.01)
Get template data fields. Body: { brand_template_id }

## Autofill

### POST /api/autofill/create ($0.02)
Autofill a brand template with data. Body: { brand_template_id, data, title? }. Async with polling.

### POST /api/autofill/status ($0.01)
Check job status. Body: { job_id }

## Imports

### POST /api/imports/create ($0.02)
Import a design from URL. Body: { url, title? }. Async with polling.

### POST /api/imports/status ($0.01)
Check job status. Body: { job_id }

## Resize

### POST /api/resize/create ($0.02)
Resize a design. Body: { design_id, width, height }. Async with polling.

### POST /api/resize/status ($0.01)
Check job status. Body: { job_id }

## Folders

### POST /api/folders/create ($0.01)
Create a folder. Body: { name, parent_folder_id? }

### POST /api/folders/get ($0.01)
Get folder details. Body: { folder_id }

### POST /api/folders/update ($0.01)
Rename a folder. Body: { folder_id, name }

### POST /api/folders/delete ($0.01)
Delete a folder. Body: { folder_id }

### POST /api/folders/items ($0.01)
List folder contents. Body: { folder_id, continuation? }

### POST /api/folders/move ($0.01)
Move item between folders. Body: { item_id, from_folder_id, to_folder_id }

## Comments (Canva Preview API)

### POST /api/comments/create ($0.01)
Add a comment. Body: { design_id, message, assignee_id? }

### POST /api/comments/get ($0.01)
Get a comment thread. Body: { design_id, thread_id }

### POST /api/comments/reply ($0.01)
Reply to a comment. Body: { design_id, thread_id, message }

### POST /api/comments/list-replies ($0.01)
List replies. Body: { design_id, thread_id, continuation? }

## 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
- Async endpoints (export, upload, autofill, import, resize) poll automatically before returning
- All paid endpoints charge on request, even if the Canva operation fails — validate inputs first
- Comments API uses Canva preview features — may change