Skip to content

API Documentation

Complete reference for EasyCast Studio APIs

Authentication

EasyCast Studio supports two auth mechanisms depending on the API you're calling.

Session (Bearer token)

Most api/* endpoints are app-internal and require a Supabase user session token.

Authorization: Bearer <session_token>

Developer API Key

The developer-facing API under /api/v1/* uses API keys.

x-api-key: <ecs_...>

Create/manage keys in the app at /api-keys.

Developer API (v1)

This is the public, API-key authenticated surface intended for external integrations. Requests must include an x-api-key header.

GET/api/v1/recordings

List recordings for the API key owner (user scoped).

Headers:

x-api-key: <ecs_...>

Query Parameters:

limit: number (default 10) offset: number (default 0) status: string (optional)

Response:

{ "success": true, "data": [/* recording rows */], "pagination": { "limit": 10, "offset": 0, "total": 10 } }

POST/api/v1/recordings

Create a new recording row for the API key owner.

Headers:

x-api-key: <ecs_...>

Request Body:

{ "title": "string", "audio_url": "string (optional)", "metadata": {} // optional JSON }

Response:

{ "success": true, "data": { /* recording row */ } }

POST/api/v1/webhooks

Register a public HTTPS endpoint for recording.completed, transcript.ready, and clip.generated events. The response reveals the signing secret once. A recording-completed event means its metadata and uploaded media are saved with a ready status; transcript and clip completion have their own events.

Required scope:

webhooks:manage

List registered endpoints with GET /api/v1/webhooks and the webhooks:read scope. Accounts may register up to 10 endpoints.

Request Body:

{ "url": "https://example.com/easycast-webhooks", "events": ["recording.completed", "transcript.ready"] }

Verify a delivery:

Hash the one-time secret to its raw 32-byte SHA-256 digest, use that digest as the HMAC-SHA256 key for the exact request body, and timing-safely compare the result to x-easycast-signature.

import { createHash, createHmac, timingSafeEqual } from 'node:crypto' const derivedKey = createHash('sha256') .update(signingSecret) .digest() const expected = Buffer.from('sha256=' + createHmac('sha256', derivedKey) .update(rawRequestBody) .digest('hex')) const received = Buffer.from(request.headers['x-easycast-signature'] ?? '') const verified = expected.length === received.length && timingSafeEqual(expected, received)

Disable, update, or delete an endpoint:

PATCH /api/v1/webhooks/{id} { "enabled": false } PATCH /api/v1/webhooks/{id} { "url": "https://example.com/new-hook", "events": ["clip.generated"] } DELETE /api/v1/webhooks/{id} Required scope: webhooks:manage

Recording APIs

POST/api/recordings/create

Create a new recording record after file upload.

Request Body:

{ "filePath": "string", "fileUrl": "string", "fileName": "string", "fileSize": number, "mimeType": "string" }

Response:

{ "success": true, "recording": { "id": "uuid", "title": "string", "status": "uploaded", "file_url": "string", "created_at": "timestamp" } }

POST/api/transcribe

Transcribe audio to text with speaker diarization. Usage tracked - counts against audio minutes limit.

Request Body:

{ "audioUrl": "string", "recordingId": "uuid" }

POST/api/enhance-audio

Enhance audio quality using AI. Premium feature - requires paid plan.

POST/api/remove-silence

Remove silence and pauses from audio. Premium feature - requires paid plan.

POST/api/remove-fillers

Remove filler words (um, uh, like, etc.) from audio.

AI Content APIs

POST/api/suggest-clips

AI-powered clip suggestions for social media. Pro+ only - uses GPT-4.

Request Body:

{ "transcript": "string", "recordingId": "uuid" }

POST/api/generate-content

Generate show notes, descriptions, and social posts. Pro+ only - uses GPT-4.

Collaboration APIs

POST/api/invite-guest

Send an email invitation to a recording guest. Requires a session bearer token; you must host the room or own the recording you invite to.

Request Body:

{ "guestEmail": "string", "guestName": "string (optional)", "roomId": "uuid (room you host)" } // or, for a recording you own: { "guestEmail": "string", "recordingId": "uuid", "recordingLink": "https://<this site>/..." }

Response:

{ "success": true, "message": "Invite sent to guest@email.com", "guestEmail": "string", "guestName": "string" }

Webhook APIs

POST/api/webhooks/stripe

Stripe payment webhook endpoint. Handles all payment lifecycle events and sends automated emails.

⚠️ Internal Use Only: This endpoint is called by Stripe servers. Requires valid Stripe signature for verification.

POST/api/check-usage-warnings

Automated cron job endpoint. Checks all users' usage and sends warning emails at 80% threshold.

🔒 Requires Authorization: Must include Bearer token with CRON_SECRET.

Headers:

Authorization: Bearer <CRON_SECRET>

Payment APIs

POST/api/create-checkout

Create Stripe checkout session for subscription purchase.

Request Body:

{ "priceId": "price_xxxxx", "successUrl": "string", "cancelUrl": "string" }

Plan Usage Allowances

These are monthly account quotas, not per-key request-rate limits. EasyCast does not currently advertise or enforce a requests-per-hour limit for the developer API.

PlanAudio MinutesStorageFeatures
Free30 minutes1 GBBasic AI
Starter30 minutes1 GBBasic AI + email support
Pro500 minutes50 GBAll AI features + priority support
BusinessUnlimited500 GBAdvanced analytics + custom branding

Error Responses

401 Unauthorized

{ "error": "Unauthorized" }

403 Forbidden - Usage Limit

{ "error": "Usage limit exceeded", "limit": 500, "used": 505, "upgradeUrl": "/pricing" }

500 Internal Server Error

{ "error": "Internal server error" }

Need Help?

For questions, support, or feature requests, contact us:

  • 📧 Email: support@easycaststudio.com
  • 💬 Discord: Join our community
  • 📚 Docs: easycaststudio.com/docs