Getting started

The SparkVox Developer API (v1) lets you turn long-form audio or transcripts into 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 or transcript text
• Review workflows that list, edit, and approve generated posts
• Publishing automations that schedule to LinkedIn, Buffer, or Publer
• 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 or transcript. Processing is asynchronous.
2. SparkVox transcribes (when needed), extracts insight moments, and writes one LinkedIn post per moment.
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 credits. 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. 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.

3. (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"

4. 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",
    "perspective": "thought_leader",
    "platforms": ["linkedin"],
    "duration_seconds": 3600
  }'

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

5. 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"

6. 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" }'

Schedule to Buffer (user must have connected Buffer 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": "buffer"
  }'

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_.

• 200 requests per 24-hour rolling window per API key.
• When the 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.

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

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/integrations - list connected publishing tools
• 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