Automate approved video work with the Storyvalo API.

Authentication

A workspace administrator creates an API key in Integrations and chooses its scopes. Send it as a bearer token from a server; never embed it in a browser or mobile app. Each request is checked against the key creator’s current membership and role: removing the creator suspends the key, and adding them back resumes it with the role they then hold, so revoke a key that must not resume. Directory deprovisioning revokes the creator’s keys, a key bound to a service principal acts as that principal instead, and workspaces that require Google sign-in suspend machine access.

Write scopes are narrow: renders:write can only request renders of projects already approved in team review, and webhooks:write manages webhook destinations. Both require the key’s creator to be a workspace administrator.

Request examples

List projects

curl https://storyvalo.com/api/v1/projects?limit=10 \
  -H "Authorization: Bearer $STORYVALO_API_KEY"

Request a render of an approved revision

Use the approved revision from the project resource. Retry with the same Idempotency-Key and body; a different body with the same key is rejected. Normal video minutes are used.

curl -X POST https://storyvalo.com/api/v1/projects/$PROJECT_ID/renders \
  -H "Authorization: Bearer $STORYVALO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: render-$PROJECT_ID-$REVISION" \
  -d '{"revision":"'"$REVISION"'"}'

Subscribe to webhooks

The response contains the signing secret once. Store it in your secret manager.

curl -X POST https://storyvalo.com/api/v1/webhooks \
  -H "Authorization: Bearer $STORYVALO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Approved projects","url":"https://hooks.example.com/storyvalo","events":["project.approved","render.completed"],"destinationApproved":true}'

Webhooks

Deliveries are signed with HMAC-SHA256 over the timestamp and raw body. Reject signatures older than five minutes. Failed deliveries retry with exponential backoff, then move to a dead-letter state an administrator can replay.

• project.approved — a reviewer approved an exact project revision
• project.published — a publishing workflow recorded a published outcome
• render.completed — a workspace render finished
• variant.ready — a language variant was approved
• import.failed — an import item exhausted its retries
• draft.created, source.changed — drafts and material source changes

Event bodies contain IDs, the event type, timestamp, version and retry count only — never credentials, source text or personal details.

import {createHmac,timingSafeEqual} from 'node:crypto';
// header: Storyvalo-Signature: t=<unix seconds>,v1=<hex>
export function verify(secret, header, rawBody, now = Date.now() / 1000) {
  const match = /^t=(\d{10}),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!match || Math.abs(now - Number(match[1])) > 300) return false;
  const expected = createHmac('sha256', secret).update(match[1] + '.' + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Errors and limits

Errors use one JSON shape with a stable code and a request ID. Each key may make a limited number of requests per minute; a 429 response includes Retry-After. Lists use opaque cursors that must be passed back unchanged.

{"error":{"code":"conflict","message":"…","requestId":"8d3c…"}}

Versioning and deprecation

The API is versioned in the URL (/api/v1) and every response carries X-API-Version. Within v1 we only add optional fields, new operations and new event types, so ignore fields you do not recognise.

A breaking change requires a new major version. Before an operation is retired, affected workspace administrators are notified and the schedule, replacement and migration examples are published here. No fixed notice period or SLA is promised yet. There are currently no announced deprecations.

Operation reference

Contract version: 2026-09-21