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.
1. Create a test key
Section titled “1. Create a test key”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.
export PODSWORTH_KEY=pw_test_...2. Create the project
Section titled “2. Create the project”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=…" } ]}3. Upload the file
Section titled “3. Upload the file”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.
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).
4. Follow it and download the result
Section titled “4. Follow it and download the result”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.
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.
The same in Python
Section titled “The same in Python”import osimport 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"])The same in TypeScript
Section titled “The same in TypeScript”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);