Talksmith Studio

API reference

Automate the same job flow as the Studio UI — create sessions, upload audio, transcribe, generate Kits, and export. Available on Pro and Studio plans.

Authentication

Create an API key in Workspace → API & webhooks. Send it on every request:

Authorization: Bearer tsk_live_…

Keys are shown once at creation. Revoke unused keys from the Studio. Session UI routes (billing checkout, webhooks config, brand editing) require Clerk sign-in — not an API key.

Scopes

Each key carries scopes. Requests without the required scope return 403 with code: "scope_required".

jobs:read — list jobs, session detail, kits catalog, languages, billing status
jobs:write — create jobs, upload audio, transcribe, generate Kits
assets:read — download individual asset PDF/Word files
export — Course Pack ZIP export
publish — direct publish to Notion / Kajabi / Teachable (Pro+)
marketplace:read — browse marketplace listings (Studio default)
brand:read — read white-label brand profiles (Studio default)

Create key with scopes

curl -X POST "$BASE/api-keys" \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline",
    "scopes": ["jobs:read", "jobs:write", "export"]
  }'

Pro keys default to job + asset + export scopes. Studio keys may also include publish, marketplace, and brand scopes.

Rate limits

API key traffic is limited to 90 requests per minute per key. Excess requests return 429 with code: "rate_limited". Browser sessions share a separate global limit.

Base URL

/api/talksmith

Replace with your deployment origin, e.g. https://your-app.railway.app/api/talksmith

Typical flow

POST /jobs — create a production session
POST /jobs/:id/upload — multipart audio file
POST /jobs/:id/transcribe — optional outputLanguage
POST /jobs/:id/generate-kit — Kit bundle
GET /jobs/:id/export — Course Pack ZIP

POST Create job

/jobs

curl -X POST "$BASE/jobs" \
  -H "Authorization: Bearer $TSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Client onboarding SOP",
    "kitId": "onboarding_kit",
    "audience": "New hires",
    "outputLanguage": "en"
  }'

outputLanguage — ISO code (en, es, fr, …). Pro+ for non-English.

POST Upload audio

/jobs/:id/upload

curl -X POST "$BASE/jobs/42/upload" \
  -H "Authorization: Bearer $TSK_KEY" \
  -F "audio=@recording.mp3"

POST Transcribe

/jobs/:id/transcribe

curl -X POST "$BASE/jobs/42/transcribe" \
  -H "Authorization: Bearer $TSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"outputLanguage":"es"}'

POST Generate Kit

/jobs/:id/generate-kit

curl -X POST "$BASE/jobs/42/generate-kit" \
  -H "Authorization: Bearer $TSK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kitId": "onboarding_kit",
    "voiceProfileId": null,
    "outputLanguage": "en"
  }'

GET Export Course Pack

/jobs/:id/export

curl -L "$BASE/jobs/42/export" \
  -H "Authorization: Bearer $TSK_KEY" \
  -o course-pack.zip

Webhooks (Studio)

Configure HTTPS endpoints in Workspace. Talksmith POSTs JSON when events fire:

job.review — assets ready for review
job.delivered — session marked delivered
kit.generated — Kit generation finished

{
  "event": "kit.generated",
  "sentAt": "2026-06-12T12:00:00.000Z",
  "job": { "id": 42, "title": "…", "status": "review", "kitId": "…" },
  "kitId": "onboarding_kit",
  "assetCount": 6
}

Each webhook gets a signing secret (auto-generated if omitted). Talksmith sends X-Talksmith-Event and X-Talksmith-Signature: t=<unix>,v1=<hmac>.

POST /webhooks/:id/test — fire a signed {"event":"test"} delivery to your endpoint (session UI / Clerk auth). Returns {ok:true, statusCode} on delivery, or {ok:false, error} if your server is unreachable or times out (5s).

Verify signature (Node.js)

const crypto = require("crypto");

function verifyTalksmithWebhook(rawBody, sigHeader, secret) {
  const parts = Object.fromEntries(sigHeader.split(",").map(p => p.trim().split("=")));
  const t = Number(parts.t), v1 = parts.v1;
  if (!t || !v1) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

GET Marketplace listings

/marketplace/listings?q=&category=&price=

curl "$BASE/marketplace/listings?q=sales&price=free" \
  -H "Authorization: Bearer $TSK_KEY"

Requires marketplace:read scope (Studio keys). Query params: q search text, category (Sales, Courses, …), price (free or paid). Featured listings sort first.

GET Brand profiles

/brand-profiles

curl "$BASE/brand-profiles" \
  -H "Authorization: Bearer $TSK_KEY"

Requires brand:read scope (Studio keys). Returns logo, accent, client label, custom host, and DNS hint for agency white-label.

Plans (reference)

Solo ($29/mo) — 8 kits · 60 min · 1 voice · 5 decks · English output
Pro Creator ($79/mo) — 30 kits · 240 min · 5 voices · 30 decks · API · marketplace · teams · multi-language · direct publish
Studio ($199/mo) — 100 kits · 600 min · unlimited voices/decks · white-label · embed widgets · webhooks · sell on marketplace

Tier gates are enforced server-side. Client UI gating is display-only.

Other endpoints

GET /billing/status — plan and usage
GET /languages — supported output languages
GET /jobs/:id — session detail, transcript, assets
GET /kits — available Kit templates

← Back to Talksmith Studio