Exports

An export turns a snapshot into a downloadable artifact — a PDF tearsheet, a slide deck, an audio briefing, an infographic, and so on. Exports are always async: you POST /v1/exports to queue a job, then poll GET /v1/exports/{id} until it completes, then download from the URL the API hands you.

Different artifact types are produced by different providers (some are generated in-process, some involve external AI providers). The API exposes the choice as a (provider, artifact_type) pair on the request body.

[!TIP] The same artifact catalogue is rendered as a gallery in the product’s Studio tab. If you’re not sure which (provider, artifact_type) pair you want, generate one from the dashboard first and inspect the resulting job — the dashboard surfaces the exact pair it sent.

Lifecycle

Creating an export

curl https://api.regsn.app/v1/exports \
  -H "Authorization: Bearer $REGSN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{
    \"snapshot_id\": \"$SNAPSHOT_ID\",
    \"artifact_type\": \"pdf\",
    \"provider\": \"internal-pdf\"
  }"

{
  "export_job_id": "e9c2…",
  "status": "pending",
  "status_url": "/v1/exports/e9c2…"
}

Request body fields:

[!WARNING] The (provider, artifact_type) pair must match one of the supported combinations exactly — otherwise you get 422 validation_error with code: "unknown". Mistyping provider is the most common reason for this.

Polling

curl https://api.regsn.app/v1/exports/$EXPORT_JOB_ID \
  -H "Authorization: Bearer $REGSN_API_KEY"

{
  "id": "e9c2…",
  "status": "running",
  "artifact_type": "pdf",
  "provider": "internal-pdf",
  "created_at": "2026-05-14T09:18:11Z",
  "completed_at": null,
  "cost_cents": null,
  "error": null,
  "download_url": null
}

status cycles through pending, running, then a terminal completed or failed. Once completed, download_url is populated and you can fetch the artifact from it (the URL is short-lived; download promptly).

A reasonable poll cadence is 5 seconds. Some artifact types (especially AI-generated video and audio) can take several minutes — design your client accordingly.

Supported artifact types

The full catalog of (provider, artifact_type) pairs is served at runtime by the dashboard; here are the categories. Specifics may change between releases — track the Changelog.

Internal artifacts — fast (≤10 seconds)

Gemini / OpenAI — image generation

NotebookLM — long-form

Require the NotebookLM sidecar to be configured on your account.

ElevenLabs — audio briefings

Google Podcast (gated)

Idempotency

Like POST /v1/scans, POST /v1/exports accepts an Idempotency-Key. The semantics are identical: same key + same body returns the cached 202 (with the same export_job_id); same key + different body is 409 idempotency_key_in_use. See Idempotency for the full table.

Both SDKs auto-generate a UUID4 idempotency key per export.

Downloading

The download_url returned on a completed job is short-lived and authenticated by your bearer token. The shape:

/api/export/jobs/{job_id}/download

Hit it with the same Authorization: Bearer … header you use for the rest of the API. The response is the binary artifact with the appropriate Content-Type (e.g. application/pdf, audio/mpeg, image/png).

curl -L -o report.pdf "https://api.regsn.app/api/export/jobs/$JOB_ID/download" \
  -H "Authorization: Bearer $REGSN_API_KEY"

Error paths

If a worker fails mid-job, the GET response has status: "failed" and an error string describing what went wrong. Failed jobs do not consume budget.

Code: end-to-end PDF

import { RegSn } from '@regsn/api';
import { writeFile } from 'node:fs/promises';
 
const client = new RegSn();
 
// 1. Queue the export.
const job = await client.exports.create({
  snapshot_id: process.env.SNAPSHOT_ID,
  artifact_type: 'pdf',
  provider: 'internal-pdf',
});
 
// 2. Poll until done.
let status;
do {
  await new Promise(r => setTimeout(r, 5000));
  status = await client.exports.get(job.export_job_id);
} while (status.status === 'pending' || status.status === 'running');
 
if (status.status !== 'completed') throw new Error(`export failed: ${status.error}`);
 
// 3. Download.
const res = await fetch(`https://api.regsn.app${status.download_url}`, {
  headers: { Authorization: `Bearer ${process.env.REGSN_API_KEY}` },
});
await writeFile('report.pdf', Buffer.from(await res.arrayBuffer()));

See also

• Snapshots — what an export is built from.
• Studio (product) — the dashboard surface that wraps this endpoint.
• Rate limits — POST /v1/exports is 30 / hour / key.
• Idempotency — retry safety on the create call.