API

Spectra.fm exposes a public API to automate exports, fetch artifacts, and integrate with your own tooling.

API Documentation

Full reference docs are available at api.spectra.fm/docs.

API Keys

All requests require an API key:

X-API-Key: YOUR_API_KEY

You can also use:

Authorization: Bearer YOUR_API_KEY

Get your API key at app.spectra.fm/settings/api-keys.

Example Requests

Who am I?

curl "https://api.spectra.fm/v1/whoami" \
  -H "X-API-Key: YOUR_API_KEY"

Create an export

curl -X POST "https://api.spectra.fm/v1/projects/YOUR_PROJECT_ID/exports" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"combinations":[{"locale":"en","theme":"light"}]}'

Poll export status

curl "https://api.spectra.fm/v1/projects/YOUR_PROJECT_ID/exports/EXPORT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

List artifacts

curl "https://api.spectra.fm/v1/projects/YOUR_PROJECT_ID/exports/EXPORT_ID/artifacts" \
  -H "X-API-Key: YOUR_API_KEY"

Download an artifact

Use downloadUrl from the artifacts response, or call:

curl -L "https://api.spectra.fm/v1/projects/YOUR_PROJECT_ID/exports/download?objectKey=projects/.../full.png&filename=full.png" \
  -H "X-API-Key: YOUR_API_KEY"

Export Flow (Async)

1. Options — GET /v1/projects/:projectId/exports/options
2. Create — POST /v1/projects/:projectId/exports
3. Poll — GET /v1/projects/:projectId/exports/:exportId
4. Artifacts — GET /v1/projects/:projectId/exports/:exportId/artifacts
5. Download — Use downloadUrl or /exports/download?objectKey=...

objectKey is an internal reference; downloadUrl is ready to use.