Utilities

Public helpers that do not require an API key.

GET/api/url-metadata?url=<encoded_url>

URL Metadata

Public helper to resolve YouTube video metadata when creating projects with source_type: url. No authentication required. Base URL: app.sparkvox.io (not under /api/v1).

Typical flow: call GET/api/url-metadata?url=... to read duration_seconds, then pass that value to POST/api/v1/projects along with the same URL.

Response 200

json

{
  "duration_seconds": 3600,
  "title": "Episode title",
  "thumbnail_url": "https://...",
  "platform": "youtube",
  "description": "Episode description",
  "channel_title": "Channel name",
  "tags": ["tag1", "tag2"],
  "source_metadata": {
    "video_id": "abc123",
    "title": "Episode title",
    "channel_title": "Channel name",
    "description": "...",
    "tags": ["tag1"],
    "duration_seconds": 3600,
    "thumbnail_url": "https://..."
  }
}

Fields may be null (or tags: []) if the video is unavailable or YOUTUBE_API_KEY is not configured. Use duration_seconds for the required duration_seconds field on POST/api/v1/projects. The web app persists source_metadata on the project for spelling context in Claude prompts during moment extraction and post generation.

Errors

Status	When
400	Missing url query parameter or unsupported URL host
502	Upstream YouTube metadata fetch failed