Podsqueeze API Documentation

Introduction

The Podsqueeze API allows users to process and transcribe podcast episodes, retrieve job statuses, manage API tokens, and register webhook notifications.

Base URL

https://europe-central2-wannabe-entrepreneur.cloudfunctions.net/podsqueeze-api

1. Get a New Token

To get a token, the user needs a Podsqueeze account. Then, they can simply go to the dashboard, click on API Access in the sidebar, and a token will be generated.

2. Start a Podsqueeze Job

Uploads an audio or video file, stores it in Firebase, and starts a transcription job. You can provide either a base64-encoded file or a public URL to the episode.

Request

POST /
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "mode": "process_episode",
  "podcastId": "<PODCAST_ID>",
  "language": "en",
  "file": "<Base64_encoded_audio/video_file>",
  "episodeUrl": "<PUBLIC_URL_TO_EPISODE>",
  "podcastTitle": "<PODCAST_TITLE>", [OPTIONAL]
  "podcastDescription": "<DESCRIPTION>", [OPTIONAL]
  "podcastImage": "<PODCAST_IMAGE_URL>", [OPTIONAL]
  "episodeTitle": "<EPISODE_TITLE>", [OPTIONAL]
  "episodeImg": "<EPISODE_IMAGE_URL>" [OPTIONAL]
}

Note: The episodeUrl must be publicly accessible and downloadable. Private or authentication-protected URLs are not supported.

Response

202 Accepted
{
  "episodeId": "<EPISODE_ID>",
  "status": "transcribing",
  "estimatedTime": "60-120 seconds"
}

3. Get Job Status

Checks the transcription progress and results.

Request

POST /
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "mode": "get_job_status",
  "episodeId": "<EPISODE_ID>",
  "podcastId": "<PODCAST_ID>"
}

Response

200 OK
{
  "status": "completed",
  "transcript": "...",
  "srt": "...",
  "speakers": { ... }
}

4. Get Job Assets

Fetches transcription and other generated episode assets.

You can optionally request only specific assets using the assets parameter. This can be a comma-separated string or an array of keys. If omitted, all assets are returned for backwards compatibility.

Request

POST /
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "mode": "get_episode_assets",
  "episodeId": "<EPISODE_ID>",
  "podcastId": "<PODCAST_ID>",
  "assets": "customContent,titles,tweets"   // optional: comma-separated string
}

Or as an array:

POST /
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "mode": "get_episode_assets",
  "episodeId": "<EPISODE_ID>",
  "podcastId": "<PODCAST_ID>",
  "assets": ["customContent", "titles", "tweets"]
}

Response

200 OK
{
  "episodeTitle: "...",
  "episodeCreationDate": "...",
  "transcript": "...",
  "srt": "...",
  "timestamps": "...",
  "quotes": "...",
  "keywords": "...",
  "bulletPoints": "...",
  "longPost": "...",
  "mentions": "...",
  "newsletter": "...",
  "shortPost": "...",
  "titles": "...",
  "tweets": "...",
  "customContent": {
    "<yourCustomKey1>": "...",
    "<yourCustomKey2>": "..."
  }
}

When assets is provided, only the requested keys are returned. Supported keys include: episodeTitle, episodeCreationDate, transcript, srt, timestamps, quotes, keywords, bulletPoints, longPost, mentions, newsletter, shortPost, titles, tweets, and customContent.

5. Get All Episodes IDs

Returns a list of all episodes for the authenticated user (as determined by the API token). Optionally, you can filter episodes by creation date using a timestamp.

Request

POST /
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

{
  "mode": "get_all_episodes_ids",
  "timestamp": "2024-06-01 00:00:00"   // optional, return only episodes created after this date
}

• The timestamp can be an ISO string (e.g., "2024-06-01 00:00:00") or epoch seconds.
• The user is determined from the API token; you cannot specify another user.

Response

200 OK
[
  {"episodeId": "abc123", "podcastId": "pod789", "creationDate": "2024-06-01 12:34:56"},
  {"episodeId": "def456", "podcastId": "pod789", "creationDate": "2024-06-02 09:10:11"}
]

Error Handling

All responses follow this format for errors:

{
  "error": "Error message"
}

Contact & Support

For questions or issues, contact support@podsqueeze.com.