# Significant Figures API

> Personalized video platform. Turn data into animated videos at scale.

## What This API Does

Significant Figures (Sig Figs) lets you create personalized, data-driven animated videos via REST API. You compose video templates from 31+ animated primitives (radar charts, bar races, stat counters, trading cards, etc.), then render unique videos for each recipient by merging their data. Think "Spotify Wrapped for any brand" — built for developers.

## Authentication

All authenticated endpoints require an API key via the `X-API-Key` header:

```
X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxx
```

Create keys at https://app.sigfigsstudio.com/settings/api-keys

### Scopes

Each API key has scoped permissions:

| Scope | Description |
|-------|-------------|
| `videos:create` | Create single render jobs |
| `videos:create:batch` | Create batch render jobs (CSV) |
| `videos:read` | Poll render status, get video URLs |
| `videos:delete` | Delete rendered videos |
| `templates:read` | List templates, view data schemas |
| `templates:write` | Create, update, fork, and delete templates |
| `projects:read` | List and view saved projects |
| `projects:write` | Create, update, delete projects |
| `billing:read` | View credit balance and usage history |
| `webhooks:manage` | Create and update webhook endpoints |
| `keys:manage` | Create and revoke API keys |

Preset bundles: `render-only`, `render-batch`, `full-access`, `read-only`, `admin`.

## Core Concepts

### Primitives
Animated scene components — the building blocks of video templates. Each primitive is a self-contained visualization (e.g., radar chart, leaderboard, stat counters). Primitives define what data they need and what animation options they support.

### Templates
An ordered list of scenes (primitives + data bindings + VO scripts). Templates define the structure and flow of a video. You can use built-in templates (emeritus, laureate, rewind, pulse, pixels) or create custom ones.

### Scenes
A scene is one primitive instance within a template, configured with:
- Which primitive to use (`primitiveId`)
- A voiceover script (`voScript`) with `[variable]` substitution
- Animation variant (`animationOption`)
- Duration and data requirements

### Rendering
Submit a template + data → get back a render job ID. The video renders in the cloud (~60 seconds). Poll for status until `complete`, then download the MP4 from `outputUrl`. Each render costs 1 credit.

### Credits
Each rendered video costs 1 credit. Free re-renders within 24h of the original (pass `originalJobId`). Credits are per-account. Check balance via the dashboard.

## Available Primitives

### Text
- **title-intro** — Name, title, and photo intro. Inputs: `name`, `title`, `photo`. Animations: `all-at-once`, `sequential`. Duration: 3s.
- **quote-card** — Highlighted quote or testimonial. Inputs: `quote`, `source`. Animations: `highlight`, `carousel`. Duration: 4s.
- **executive-letter** — Signed letter with signature animation. Inputs: `bodyLines[]`, `senderName`, `senderTitle`. Animations: `clip-reveal`. Duration: 5s.

### Data Viz
- **radar** — Multi-axis fingerprint showing relative strengths. Inputs: `categories[]`, `values[]`. Animations: `per-dimension`. Duration: 8s.
- **bar-race** — Animated ranking race over time. Inputs: `items[]`, `values[]`. Animations: `animate-on-init`. Duration: 6s.
- **leaderboard** — Top-to-bottom ranking reveal. Inputs: `items[]`, `scores[]`. Animations: `top-reveal`, `bottom-reveal`. Duration: 5s.
- **world-map** — Geographic data with pulse or fill animation. Inputs: `countries[]`. Animations: `pulse`, `fill`, `fly-in`. Duration: 5s.
- **timeline** — Event timeline with scroll animation. Inputs: `events[]`. Animations: `auto-scroll`, `step-by-step`. Duration: 8s.
- **stat-counters** — Animated number counters. Inputs: `metrics[]`. Animations: `count-up`, `pop`, `stagger`. Duration: 14s.
- **proportion-donut** — Proportion breakdown with center stat. Inputs: `categories[]`, `values[]`. Animations: `clockwise`, `counterclockwise`. Duration: 4s.
- **calendar-heatmap** — Activity heatmap across 365 days. Inputs: `dailyValues[]`. Animations: `vertical`, `horizontal`. Duration: 5s.
- **comparison-bars** — You vs benchmark side-by-side. Inputs: `metrics[]`, `benchmarks[]`. Animations: `bars-grow`. Duration: 4s.
- **percentile-bar** — Bar fill showing percentile ranking. Inputs: `percentile`, `category`. Animations: `fill`, `countdown-tick`. Duration: 5s.
- **funnel** — Stage-by-stage conversion funnel. Inputs: `stages[]`, `counts[]`. Animations: `top-down`, `bottom-up`. Duration: 5s.
- **mini-charts-rows** — Small multiples showing trends. Inputs: `metrics[]`, `timeSeries[]`. Animations: `stagger`, `sync`. Duration: 4s.
- **pictogram** — Icon grid showing proportion. Inputs: `total`, `highlighted`. Animations: `grid-fill`, `count-up`. Duration: 4s.
- **streak-counter** — Flame-scale streak animation. Inputs: `streakCount`, `unit`. Animations: `flame-scale`. Duration: 4s.
- **trophy-case** — Achievement display. Inputs: `trophies[]`. Animations: `all-then-highlight`, `sequential`. Duration: 5s.
- **rating-reveal** — Star/score rating with flip animation. Inputs: `items[]`, `ratings[]`. Animations: `flip`. Duration: 4s.

### Gamification
- **trading-card** — Collectible card with stats. Inputs: `name`, `stats[]`, `rarity`. Animations: `card-flip`, `holographic-tilt`. Duration: 5s.
- **personality-badge** — Type/badge reveal. Inputs: `typeName`, `traits[]`. Animations: `badge-drop`, `badge-pop`. Duration: 4s.
- **badge-collection** — Achievement grid with locked/unlocked. Inputs: `badges[]`. Animations: `grid-reveal`, `gentle-float`. Duration: 5s.

### Comparison
- **vs-card** — Side-by-side period comparison. Inputs: `leftLabel`, `rightLabel`, `stats[]`. Animations: `sequential-reveal`. Duration: 5s.

### Media
- **logo-carousel** — Grid or scroll of partner logos. Inputs: `logos[]`. Animations: `grid`, `scroll`. Duration: 4s.
- **image-compare** — Side-by-side image comparison. Inputs: `imageBefore`, `imageAfter`. Animations: `slider`, `wipe`, `fade`. Duration: 4s.

### Engagement
- **choice-reveal** — Quiz or poll result reveal. Inputs: `question`, `options[]`, `mode`. Animations: `quiz`, `poll-conformity`, `poll-divergence`. Duration: 5s.
- **cta-card** — End-of-video call-to-action with customizable buttons and message. Inputs: `headline`, `subtext`, `primaryCtaText`, `primaryCtaUrl`, `secondaryCtaText`, `secondaryCtaUrl`. Animations: `fade-in`, `slide-up`, `pop`. Duration: 5s.
- **path-selector** (beta) — Interactive choice point — viewer selects a path (renders as animated options in MP4). Inputs: `question`, `options[]`, `optionIcons[]`. Animations: `fan-out`, `stack-reveal`. Duration: 5s.

### Narrative
- **chat-replay** — Animated text message conversation. Inputs: `messages[]`, `senderName`. Animations: `sequential`. Duration: 5s.

### People
- **team-grid** — Meet the team with photos. Inputs: `members[]`. Animations: `drop-in`. Duration: 5s.

### Branding
- **outro** — Logo + CTA closing. Inputs: `logo`, `tagline`, `cta`. Animations: `fade`, `slide`. Duration: 3s.

## Composing a Template

### Step 1: Browse Primitives
```
GET /api/primitives
```
Review available primitives and their data requirements.

### Step 2: Create a Template
```
POST /api/templates
X-API-Key: sf_live_xxx

{
  "name": "Customer Onboarding",
  "description": "Welcome video for new customers",
  "scenes": [
    {
      "primitiveId": "title-intro",
      "label": "Welcome",
      "defaultDuration": 3,
      "voScript": "Welcome to the team, [person_name]. We're thrilled to have [company_name] on board.",
      "animationOption": "sequential",
      "dataRequired": [
        "person_name",
        "company_name",
        "photo"
      ]
    },
    {
      "primitiveId": "stat-counters",
      "label": "What's Ahead",
      "defaultDuration": 4,
      "voScript": "Here's what your first 30 days look like.",
      "animationOption": "count-up",
      "dataRequired": [
        "metrics[]"
      ]
    },
    {
      "primitiveId": "timeline",
      "label": "Onboarding Milestones",
      "defaultDuration": 8,
      "voScript": "We've mapped out key milestones to get you up and running.",
      "animationOption": "step-by-step",
      "dataRequired": [
        "events[]"
      ]
    },
    {
      "primitiveId": "cta-card",
      "label": "Book Kickoff",
      "defaultDuration": 5,
      "voScript": "Ready to get started? Book your kickoff call today.",
      "animationOption": "slide-up",
      "dataRequired": [
        "headline",
        "primaryCtaText",
        "primaryCtaUrl"
      ]
    }
  ],
  "dataSlots": [
    {
      "key": "person_name",
      "label": "Name",
      "type": "text",
      "required": true
    },
    {
      "key": "company_name",
      "label": "Company",
      "type": "text",
      "required": true
    }
  ],
  "defaults": {
    "voiceId": "en-GB-RyanNeural",
    "accentColor": "#10b981",
    "resolution": "1080p"
  },
  "tags": [
    "onboarding",
    "welcome"
  ]
}
```

### Step 3: (Optional) Use AI to Compose
Instead of manually picking primitives, describe what you want:
```
POST /api/prompt-builder
X-API-Key: sf_live_xxx

{ "prompt": "Create a customer onboarding video with welcome, key metrics, milestone timeline, and a CTA", "mode": "create", "currentState": { "id": "", "name": "", "scenes": [], "tags": [], "visibility": "private" } }
```
The AI selects primitives, configures scenes, and writes VO scripts.

### Step 4: Generate VO Scripts (Optional)
```
POST /api/generate-script

{ "scenes": [...your scenes...], "inputData": { "person_name": "Sarah Chen", "company_name": "Acme Corp" }, "tone": "professional" }
```

### Step 5: Render a Video
```
POST /api/render

{
  "templateId": "clxxxxxxxxxxxxxxxxxx",
  "data": {
    "person_name": "Sarah Chen",
    "company_name": "Acme Corp",
    "role": "VP of Marketing"
  },
  "brand": {
    "accentColor": "#10b981"
  },
  "audio": {
    "voiceId": "en-GB-RyanNeural"
  },
  "output": {
    "resolution": "1080p"
  }
}
```

### Step 6: Poll for Completion
```
GET /api/render/{jobId}
```
Poll every 5-10 seconds until `status` is `"complete"`, then use `outputUrl` to download the MP4.

## Endpoints

### admin
- **GET, POST** `/api/admin/snapshot`

### analytics
- **GET** `/api/analytics/campaign/{batchId}`
- **GET** `/api/analytics/campaign/{batchId}/ab`
- **GET** `/api/analytics/campaign/{batchId}/heatmap`
- **GET** `/api/analytics/video/{videoId}`

### campaigns
- **GET, POST, PATCH** `/api/campaigns/{batchId}/review`
- **GET, POST** `/api/campaigns/{batchId}/review/comments`

### checkout
- **POST** `/api/checkout`

### cron
- **GET** `/api/cron/cleanup`

### embed
- **GET** `/api/embed/{id}`
- **POST** `/api/embed/{id}/view`

### events
- **POST** `/api/events/ingest`

### exports
- **GET, POST** `/api/exports`

### generate-script
- **POST** `/api/generate-script`

### integrations
- **GET** `/api/integrations/{provider}/auth`
- **GET** `/api/integrations/{provider}/callback`

### keys
- **GET, POST** `/api/keys`
- **POST, PATCH, DELETE** `/api/keys/{id}`

### languages
- **GET** `/api/languages`

### openalex
- **GET** `/api/openalex`

### openapi
- **GET** `/api/openapi`

### primitives
- **GET** `/api/primitives`

### projects
- **GET, POST** `/api/projects`
- **GET, PATCH, DELETE** `/api/projects/{id}`
- **GET** `/api/projects/{id}/versions`
- **GET** `/api/projects/{id}/versions/{versionId}`

### prompt-builder
- **POST** `/api/prompt-builder`

### render
- **POST** `/api/render`
- **GET, PATCH** `/api/render/{id}`
- **GET, POST** `/api/render/batch`
- **POST** `/api/render/cloud`
- **GET, POST** `/api/render/wrapped`
- **GET, PATCH** `/api/render/wrapped/jobs`

### send-email
- **POST** `/api/send-email`
- **POST** `/api/send-email/batch`

### sheets
- **GET** `/api/sheets`
- **GET** `/api/sheets/{sheetId}`
- **GET** `/api/sheets/{sheetId}/data`
- **GET, DELETE** `/api/sheets/status`

### templates
- **GET, POST** `/api/templates`
- **GET, PUT, PATCH, DELETE** `/api/templates/{id}`
- **POST** `/api/templates/{id}/use`

### thumbnail
- **POST** `/api/thumbnail`

### track
- **POST** `/api/track`
- **GET** `/api/track/pixel/{videoId}`

### translate
- **POST** `/api/translate`

### triggers
- **GET, POST** `/api/triggers`
- **GET, PATCH, DELETE** `/api/triggers/{id}`

### tts
- **POST** `/api/tts`

### user
- **GET** `/api/user/credits`
- **GET, PUT, DELETE** `/api/user/keys`

### v
- **GET, POST** `/api/v/{id}/remix`

### videos
- **GET, POST** `/api/videos`

### webhook
- **POST** `/api/webhook`

### webhooks
- **POST** `/api/webhooks/deploy`

## Built-in Templates

| Slug | Brand Name | Category | Use Case | Published |
|------|-----------|----------|----------|-----------|
| `emeritus` | Emeritus | portrait | Celebrate a research career | ✅ |
| `laureate` | Laureate | portrait | Honor an author's body of work | ✅ |
| `rewind` | Rewind | wrapped | Turn a year into a story | ✅ |
| `pulse` | Pulse | recap | Animated monthly achievement report | ✅ |
| `pixels` | Pixels | recap | 365 days of showing up, revealed | ✅ |
| `welcome` | Welcome | onboarding | Welcome Video | — |
| `handshake` | Handshake | onboarding | Client Welcome | — |
| `launchpad` | Launchpad | onboarding | First Week Recap | — |
| `century` | Century | milestone | 100th Milestone | — |
| `streak` | Streak | milestone | Streak Celebration | — |
| `milestone` | Milestone | retention | 1 Year Anniversary | — |
| `comeback` | Comeback | retention | We Miss You | — |

## Supported Languages

English (`en`), English (UK) (`en-GB`), Spanish (`es`), French (`fr`), German (`de`), Portuguese (`pt`), Portuguese (Brazil) (`pt-BR`), Japanese (`ja`), Korean (`ko`), Chinese (Mandarin) (`zh`), Arabic (`ar`), Hindi (`hi`), Italian (`it`), Dutch (`nl`), Polish (`pl`), Russian (`ru`), Turkish (`tr`), Thai (`th`), Vietnamese (`vi`), Swedish (`sv`).

## Rate Limits

| Endpoint | Limit | Window | Scope |
|----------|-------|--------|-------|
| GET /api/templates | 30 | 1 min | IP |
| POST /api/templates | 10 | 1 min | User |
| PATCH/PUT /api/templates/{id} | 30 | 1 min | User |
| DELETE /api/templates/{id} | 10 | 1 min | User |
| POST /api/render | 30 | 1 min | User |
| GET /api/render/{id} | 120 | 1 min | User |
| POST /api/render/batch | 5 | 1 min | User |
| POST /api/prompt-builder | 10 | 1 min | User |
| POST /api/generate-script | 5 | 1 min | User |

Concurrent render limits: free=1, studio=5, enterprise=20.

## Pricing

Each rendered video costs **1 credit**.

- **Free tier:** Watermarked output, 720p/1080p only, 1 concurrent render, 10 batch max
- **Studio tier:** No watermark, up to 4K, custom voices (BYOK ElevenLabs), 5 concurrent, 100 batch max
- **Enterprise tier:** Everything in Studio + 20 concurrent, 1000 batch max, priority rendering

Free re-render within 24h of the original (pass `originalJobId`).

## OpenAPI Spec

Machine-readable spec: https://app.sigfigsstudio.com/openapi.json