Skip to content

Quickstart

This walks through one project with a test key: everything behaves like a live project (statuses, webhooks, the delivery) except that nothing is processed and nothing is charged. Switch to a live key when you’re ready.

Sign in at app.podsworth.com, open your account page, and under API keys create a key in Test mode with these permissions: read projects, create and upload projects. Copy the secret: it’s shown once.

Terminal window
export PODSWORTH_KEY=pw_test_...
Terminal window
curl https://api.podsworth.com/v1/projects \
-H "Authorization: Bearer $PODSWORTH_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Episode 12", "files": [{"fileName": "episode-12.wav"}], "submit": true}'

submit: true means it starts by itself as soon as its file is in. The file comes back with an uploadUrl:

{
"id": "prj_9f2c41d0b8e64a7c9a11",
"status": "draft",
"mode": "test",
"files": [
{
"id": "file_8c1d4f0e2b7a49d1a3f0",
"fileName": "episode-12.wav",
"status": "awaiting_upload",
"uploadUrl": "https://…s3.us-east-2.amazonaws.com/uploads/…?X-Amz-Signature=…"
}
]
}

PUT the file to its uploadUrl. The file is the whole request body: no form, no other headers, and no Authorization either (the URL is signed, and works for three hours). The bytes go straight to our storage, so a large file never passes through the API.

Terminal window
curl -T episode-12.wav "<uploadUrl>"

We check the file as soon as it lands (it’s measured, and must be audio or video we can read), and the project moves on: validating, then queued. If something’s wrong it’s rejected instead, with a reason you can fix before submitting again (Projects).

Poll GET /v1/projects/{id} (every 10 seconds or so), or add a webhook and wait for project.completed. A test project takes about a minute.

Terminal window
curl https://api.podsworth.com/v1/projects/prj_9f2c41d0b8e64a7c9a11 \
-H "Authorization: Bearer $PODSWORTH_KEY"

When it’s completed, downloadUrl is the whole delivery as a zip, outputs lists each file with its own link, and manifestUrl describes them. Links last an hour: fetch the project again for fresh ones.

import os
import time
import requests
API = "https://api.podsworth.com"
HEADERS = {"Authorization": f"Bearer {os.environ['PODSWORTH_KEY']}"}
project = requests.post(f"{API}/v1/projects", headers=HEADERS, json={
"name": "Episode 12", "files": [{"fileName": "episode-12.wav"}], "submit": True}).json()
with open("episode-12.wav", "rb") as f:
requests.put(project["files"][0]["uploadUrl"], data=f).raise_for_status()
while project["status"] not in ("completed", "failed", "rejected", "cancelled"):
time.sleep(10)
project = requests.get(f"{API}/v1/projects/{project['id']}", headers=HEADERS).json()
print(project["status"], project["downloadUrl"] or project["rejection"] or project["failure"])

Node 20 or later (built-in fetch):

import { readFile } from "node:fs/promises";
const API = "https://api.podsworth.com";
const headers = { Authorization: `Bearer ${process.env.PODSWORTH_KEY}`, "Content-Type": "application/json" };
let project = await (await fetch(`${API}/v1/projects`, {
method: "POST", headers,
body: JSON.stringify({ name: "Episode 12", files: [{ fileName: "episode-12.wav" }], submit: true }),
})).json();
const put = await fetch(project.files[0].uploadUrl, { method: "PUT", body: await readFile("episode-12.wav") });
if (!put.ok) throw new Error(`upload failed: ${put.status}`);
while (!["completed", "failed", "rejected", "cancelled"].includes(project.status)) {
await new Promise((r) => setTimeout(r, 10_000));
project = await (await fetch(`${API}/v1/projects/${project.id}`, { headers })).json();
}
console.log(project.status, project.downloadUrl ?? project.rejection ?? project.failure);
  • Files: upload first and decide later, imports from links, Dropbox and Google Drive.
  • Projects: statuses, multi-track projects, changing a project, processing it again.
  • Webhooks: stop polling.
  • Test mode: force a failure to test your error handling.