Getting started

The SparkVox Developer API (v1) lets you capture expertise from long-form audio or transcripts and draft LinkedIn posts programmatically. You submit content, SparkVox runs the same processing pipeline as the web app, and you receive results via REST and webhooks.

What you can build

• Ingest pipelines that create projects from podcast URLs, transcript text, or files in Google Drive, Dropbox, or OneDrive
• Review workflows that list, edit, and approve generated posts
• Publishing automations that publish to LinkedIn
• Image workflows that generate AI visuals or attach your own uploads
• Event-driven integrations using signed webhooks (project.ready, project.failed)

How it works

1. You create a project with a public URL, transcript, or cloud file from connected Google Drive, Dropbox, or OneDrive. Processing is asynchronous.
2. SparkVox transcribes (when needed), scores and curates insight moments, then writes one LinkedIn post per curated moment (best-of-two hook ranking per moment in the app pipeline).
3. When generation finishes, project.ready fires. You fetch posts under that project.
4. You PATCH posts to approve, edit copy, add images, or schedule to a connected tool.

Core resources

Reading these docs

• Guides (this section) explain concepts, standards, and workflows
• API standards and Error handling define conventions and status codes
• API Reference lists request/response shapes per endpoint
• Quickstart walks through a minimal integration with curl examples

This walkthrough assumes you have a SparkVox account with available processing time. Replace sk_sparkvox_YOUR_KEY with a key from Settings → Developer.

1. Create an API key

Create a key in the app under Settings → Developer. Keys start with sk_sparkvox_.

Create keys at https://app.sparkvox.io/settings/developer

2. Check balance (optional)

curl https://app.sparkvox.io/api/v1/account \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY"

Returns processing_minutes (available processing time) and rate_limit headroom for reads and writes separately (2,000 GET and 100 write requests per 24h per key). See Get Account in the API reference.

3. Register a webhook

curl -X POST https://app.sparkvox.io/api/v1/webhooks \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/sparkvox-webhook",
    "events": ["project.ready", "project.failed"]
  }'

Store the secret from the response. Use it to verify X-SparkVox-Signature on incoming requests. See Events & signatures.

4. (Optional) Resolve YouTube metadata

For YouTube source URLs, fetch duration_seconds before creating the project. No API key required.

curl "https://app.sparkvox.io/api/url-metadata?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DVIDEO_ID"

5. Create a project

curl -X POST https://app.sparkvox.io/api/v1/projects \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Podcast Episode",
    "source_type": "url",
    "source_url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "source_material": "Podcast / Interview",
    "perspective": "host",
    "platforms": ["linkedin"],
    "duration_seconds": 3600
  }'

Response is 202 with project_id and status pending. Processing runs in the background.

6. Handle project.ready

When your webhook receives project.ready, note project_id and posts_url from the payload. List posts:

curl "https://app.sparkvox.io/api/v1/projects/PROJECT_ID/posts" \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY"

7. Approve or schedule a post

Approve in SparkVox only (no external publish):

curl -X PATCH "https://app.sparkvox.io/api/v1/projects/PROJECT_ID/posts/POST_ID" \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }'

Publish to LinkedIn (user must have connected LinkedIn in Settings → Integrations):

curl -X PATCH "https://app.sparkvox.io/api/v1/projects/PROJECT_ID/posts/POST_ID" \
  -H "Authorization: Bearer sk_sparkvox_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "provider": "linkedin"
  }'

All v1 endpoints require an API key passed in the Authorization header:

Authorization: Bearer sk_sparkvox_<key>

Generate keys in Settings → Developer. Keys start with sk_sparkvox_. Up to 5 keys per account. Auth accepts any Bearer token starting with sk_.

• 2,000 read requests (GET) per 24-hour rolling window per API key.
• 100 write requests (POST, PATCH, DELETE) per 24-hour rolling window per API key.
• When a limit is exceeded the API returns 429 Too Many Requests.
• The error body describes the limit; the message may include seconds until reset.
• Some responses include a Retry-After header when rate limited.
• Check headroom with GET/api/v1/account (read and write counts separately).

All dates are UTC. v1 remains the current major version; new endpoints and fields are additive unless noted otherwise.

2026-09-16

Cloud import on provider google-drive accepts native Google Docs via mime_type application/vnd.google-apps.document. SparkVox exports the document to plain text server-side (same ingest path as transcript files). Web app Import from cloud also supports TXT on all providers; API plain text should use source_type transcript.

Added

• google-drive cloud projects: application/vnd.google-apps.document (Google Docs) alongside audio/mpeg and application/x-subrip

Changed

• Rate limit documentation: 2,000 read (GET) and 100 write requests per API key per rolling 24h (GET/account exposes headroom)

2026-08-10

On-demand generate-image now matches the in-app pipeline: Claude Sonnet drafts a hook-anchored visual brief, then fal.ai Flux renders the 16:9 image (heuristic fallback if the brief step fails).

Changed

• POST/api/v1/projects/:id/posts/:postId/generate-image uses Sonnet hook-anchored brief → Flux (same as the app)

2026-08-03

Documented app-only publish routes used by the native LinkedIn scheduler (session auth, not API key). Smart schedule pre-fill reads GET/api/publish/channel-scheduling-anchors per channel.

Added

• App-only endpoints reference page (channel-scheduling-anchors, queue-scheduled, publish-now)

2026-07-29

Granola notetaker support: list notes with GET/api/v1/notetaker-meetings?provider=granola and create projects with source_type notetaker and provider granola. Connect Granola in the app under Settings → Integrations first (Business or Enterprise API key required on the Granola side).

Added

• provider granola on GET/api/v1/notetaker-meetings
• provider granola on POST/api/v1/projects with source_type notetaker
• integrations list returns kind: notetaker for Fireflies, Fathom, Granola, Google Meet, and Zoom

2026-06-15

POST/projects cloud import adds provider onedrive alongside google-drive and dropbox when OneDrive is connected under Settings → Integrations.

Added

• provider onedrive for source_type cloud
• App-only OneDrive OAuth, picker, and /api/onedrive-ingest endpoints (see App-only endpoints)

2026-06-14

POST/projects accepts source_type cloud for Google Drive, Dropbox, or OneDrive project import (MP3, SRT via API; MP3, TXT, SRT in web app) when the provider is connected under Settings → Integrations.

Added

• source_type cloud with provider google-drive, dropbox, or onedrive, file_id, file_name, mime_type, and optional size
• Server-side download from connected Google Drive, Dropbox, or OneDrive and ingest in one request
• provider dropbox and onedrive supported alongside google-drive

2026-06-10

API docs aligned with sparkvox-app v1 source lens model: source_material field, slug-only perspectives (legacy pipeline ids return 400), awaiting_speaker status, expanded url-metadata fields, MP4 upload limits, PATCH provider + status requirement, and project.failed error variants.

Changed

• POST/projects accepts source_material (Podcast / Interview or Knowledge & Advisory) and perspective slugs only
• Legacy pipeline ids thought_leader, expert_guest, and show_brand return 400
• Projects store source_material and professional_perspective on each row

2026-06-01

Expanded v1 coverage for integrations, project lifecycle, post images, and webhook management. No breaking changes to existing request or response shapes.

Added

• GET/api/url-metadata - public YouTube metadata helper (no API key)
• GET/api/v1/account - processing time balance and rate-limit headroom
• GET/api/v1/integrations - list connected LinkedIn accounts
• DELETE/api/v1/projects/:id - delete a project and associated content
• GET/api/v1/projects/:id/posts/:postId - fetch a single post
• POST/api/v1/projects/:id/posts/:postId/generate-image - async AI image generation
• POST/api/v1/projects/:id/posts/:postId/upload-url - presigned custom image upload
• GET/api/v1/webhooks - list registered webhooks

Changed

• List posts responses include publish_tool
• Documented image_url sentinel values: __generating__, __error__, or a normal https URL
• PATCH post image_url accepts SparkVox R2 and legacy Supabase public URLs
• Not in v1: removed on-demand image generation (now available via generate-image); added OAuth connect via API note

2026-05-01 - v1 initial

Developer API v1 launched (Phase 11). Long-form LinkedIn posts only.

Added

• POST/api/v1/projects, GET/api/v1/projects, GET/api/v1/projects/:id
• GET/api/v1/projects/:id/posts, PATCH/api/v1/projects/:id/posts/:postId
• POST/api/v1/webhooks, DELETE/api/v1/webhooks/:id
• Webhook events: project.ready, project.failed (HMAC verification)
• API key auth, 200 requests per 24h rate limit