API Reference

Authentication

All endpoints require an API key in the Authorization header. API keys are not scoped — they have full access to your account.

Authorization: Bearer <your-api-key>

Go to Dashboard → API Keys, enter a name, and click +. Copy the key immediately — it won't be shown again.

Base URL

https://aurorashot.com

All paths in this reference are relative to this base.

Cards

Cards are the core resource. Every card has a type, an optional name, and a state object with all tool-specific fields. Partial state is accepted on create — missing fields are filled with per-type defaults.

Card object

{
  "id":        "2c1571c5-c040-47c3-9bbb-a8a73ee02d36",
  "userId":    "r303GGKfkuwNTgsCEEYNBrZegpxpv5LJ",
  "type":      "phone-mockup",
  "name":      "My iPhone Mockup",
  "state":     { ... },
  "createdAt": "2026-04-14T17:15:42.799Z",
  "updatedAt": "2026-04-14T17:15:42.799Z"
}

List cards

curl https://aurorashot.com/api/cards \
  -H "Authorization: Bearer <key>"

# filtered
curl "https://aurorashot.com/api/cards?type=metric-card" \
  -H "Authorization: Bearer <key>"

Create a card

curl -X POST https://aurorashot.com/api/cards \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type":  "metric-card",
    "name":  "Monthly Revenue",
    "state": { "label": "MRR", "value": "12,400", "unit": "$", "change": "+8%" }
  }'

Returns 201 with the created card. Returns 403 if your plan's card limit is reached.

Get a card

curl https://aurorashot.com/api/cards/abc123 \
  -H "Authorization: Bearer <key>"

Returns the card object, or 404 if not found or not owned by you.

Update a card

State patches are shallow-merged into the existing state — only send the fields you want to change.

curl -X PATCH https://aurorashot.com/api/cards/abc123 \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"state": {"value": "14,200", "change": "+14%"}}'

Delete a card

curl -X DELETE https://aurorashot.com/api/cards/abc123 \
  -H "Authorization: Bearer <key>"

Returns { "ok": true }.

Public card read

Returns id, type, name, and state without authentication. No user data is exposed. Useful for sharing or embedding.

curl https://aurorashot.com/api/cards/abc123/public

Render

Returns a hosted URL at /c/:id where the card renders full-screen. Open it in a browser, screenshot it with Puppeteer or Playwright, or embed it in an iframe.

Two modes — reference an existing card by ID, or pass state inline (auto-saves a card).

Mode 1 — existing card

curl -X POST https://aurorashot.com/api/render \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"cardId": "abc123"}'

Mode 2 — inline state

curl -X POST https://aurorashot.com/api/render \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool":  "metric-card",
    "name":  "Quick Render",
    "state": { "label": "Signups", "value": "3,201", "change": "+22%" }
  }'

Response

{
  "cardId":    "abc123",
  "type":      "metric-card",
  "renderUrl": "https://aurorashot.com/c/abc123"
}

Export

Export a card as PNG, GIF, or MP4. The endpoint returns a renderUrl — opening it in any browser automatically runs the export and triggers a download.

GIF and MP4 are generated entirely in the browser using the same pipeline as the card editor (html-to-image + gif.js for GIF, MediaRecorder for MP4). No server-side rendering or headless browser is involved — the browser is the renderer.

Same two modes as /api/render — existing card or inline state.

PNG export

curl -X POST https://aurorashot.com/api/export \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "abc123",
    "format": "png",
    "options": { "pixelRatio": 3 }
  }'

GIF export

curl -X POST https://aurorashot.com/api/export \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "cardId": "abc123",
    "format": "gif",
    "options": {
      "pixelRatio": 2,
      "quality": 6,
      "animSpeed": "fast",
      "animEasing": "snappy",
      "initialDelay": 400,
      "finalDelay": 1000
    }
  }'

MP4 export

curl -X POST https://aurorashot.com/api/export \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "metric-card",
    "name": "MRR animation",
    "state": { "label": "MRR", "value": "12,400", "change": "+8%" },
    "format": "mp4",
    "options": { "fps": 60, "pixelRatio": 2, "animSpeed": "medium" }
  }'

Body fields

Options

Response

{
  "cardId":    "abc123",
  "format":    "gif",
  "renderUrl": "https://aurorashot.com/c/abc123?autoexport=gif&pixelRatio=2&quality=6&animSpeed=fast"
}

Open renderUrl in a browser to run the export. The page shows a progress indicator, then auto-downloads the file when complete. For automation, poll window.__aurorashot_export — it is set to { status: 'done', format, url } when the download is ready.

Journey export

Export a full Journey sequence (multi-card animated GIF or MP4). Pass either an existing journeyId or inline state — the same two modes as card export. Journey export supports gif and mp4 only (not PNG, since journeys are inherently animated).

curl -X POST https://aurorashot.com/api/export/journey \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "journeyId": "<id>",
    "format": "gif",
    "options": { "fps": 30, "animSpeed": "medium" }
  }'

Or save a journey first, then export it:

# 1. Save journey state
curl -X POST https://aurorashot.com/api/journeys \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My Journey", "state": { ...journeyState } }'
# → { "id": "<journeyId>", ... }

# 2. Export it
curl -X POST https://aurorashot.com/api/export/journey \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "journeyId": "<journeyId>", "format": "mp4" }'
# → { "journeyId", "format", "renderUrl" }

Output resolution. Journey GIFs and MP4s are rendered into a fixed canvas (default 1920×1080). The resolution is stored on the journey at state.journeySettings.exportResolution so it round-trips through the journey CRUD endpoints. You can also override per-export with ?width= and ?height= query params on the returned renderUrl.

// Inside journey state:
"journeySettings": {
  "exportResolution": {
    "width": 1920,
    "height": 1080,
    "preset": "landscape-16-9"  // or "portrait-9-16", "square-1-1", "portrait-4-5", "custom"
  },
  "exportFps": 30,
  // ... other motion settings ...
}

Journeys

Journeys are multi-card animated sequences. Save a journey's state to the API, then use /api/export/journey to get a renderUrl for GIF or MP4 export.

List journeys

Create a journey

Get a journey

Update a journey

Delete a journey

Card Types

Use these strings as the type field when creating cards, or as tool in /api/render.

Identities

Identities store reusable profile data — name, handles, avatar, repo — that auto-fills across card tools in the UI.

Identity endpoints currently require session cookie auth (web UI only). API key support is coming in a future beta release.

Identity fields

Errors

All errors return JSON with an error string and an appropriate HTTP status.

{ "error": "Human-readable message" }

Changelog