Episodes

Create, list, retrieve, retry, and delete changelog-to-audio/video episodes.

Create an Episode

POST/v1/episodes

Create a new changelog-to-audio or video episode. Audio episodes are processed synchronously and return immediately with results. Video episodes are processed asynchronously and return a poll URL.

Request Body

Parameter	Type	Required	Description
`content`	string	Required	Changelog content in markdown format. Maximum 50KB.
`mode`	string changelogproduct-feature	Optional(default: `changelog`)	Content type being converted.
`output_format`	string audiovideo	Optional(default: `audio`)	Desired output format. Audio is synchronous, video is asynchronous. (Video coming soon)
`settings`	object	Optional	Episode settings. See Settings Object below.
`screenshot_urls`	string[]	Optional	HTTPS URLs of product screenshots for video. Maximum 20. (Video coming soon)
`webhook_url`	string	Optional	HTTPS URL to receive completion webhook notification.
`wait`	boolean	Optional(default: `false`)	For video: block until completion (max 90 seconds). (Video coming soon)
`further_details`	string	Optional	Additional context about this changelog for the AI script generator. Maximum 2000 characters.
`use_history`	boolean	Optional(default: `true`)	Whether to include previous changelogs as context for the AI script generator.
`history_limit`	integer	Optional(default: `10`)	Number of previous changelogs to include as context (1-20).
`public_url`	boolean	Optional(default: `false`)	If true, creates a publicly shareable listen page and embeddable player.

Settings Object

Settings Object Reference

Field	Type	Default	Description
`product_name`	string	-	Product or company name to use in the script.
`version`	string	-	Version number to emphasize (e.g., "2.0.0").
`tone`	string casualprofessionalenthusiastictechnical	`casual`	Voice tone for the generated script.
`audience`	string	-	Target audience description (e.g., "developers", "general").
`verbosity`	string briefnormaldetailed	`normal`	Script length preference.
`duration`	string briefnormaldetailed	`normal`	Alias for verbosity.

Body

{
  "content": "## v2.0.0 - 2026-01-15\n\n### Added\n- Dark mode support\n- Real-time collaboration\n\n### Fixed\n- Login timeout issue",
  "mode": "changelog",
  "output_format": "audio",
  "settings": {
    "product_name": "Acme App",
    "version": "2.0.0",
    "tone": "casual"
  },
  "further_details": "This release focuses on user experience improvements after customer feedback.",
  "use_history": true,
  "history_limit": 5,
  "public_url": true
}

Video Episode (Async)Coming Soon

Video episodes return immediately with status processing and a poll_url to check progress:

Video Response (202 Accepted)

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "output_format": "video",
    "poll_url": "https://api.logtalk.io/v1/episodes/550e8400-e29b-41d4-a716-446655440000",
    "estimated_completion_seconds": 60,
    "created_at": "2026-01-18T14:30:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:00.000Z"
}

List Episodes

GET/v1/episodes

Returns a paginated list of episodes for your organization. Results are sorted by creation date (newest first).

Query Parameters

Parameter	Type	Required	Description
`status`	string pendingprocessinggeneratingcompletedfailed	Optional	Filter by episode status.
`mode`	string changelogproduct-feature	Optional	Filter by episode mode.
`output_format`	string audiovideo	Optional	Filter by output format. (Video coming soon)
`created_after`	string	Optional	Filter episodes created after this ISO 8601 timestamp.
`created_before`	string	Optional	Filter episodes created before this ISO 8601 timestamp.
`limit`	integer	Optional(default: `20`)	Maximum results per page (1-100).
`cursor`	string	Optional	Pagination cursor from previous response.

200 OK

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "mode": "changelog",
      "source": "api",
      "progress_percent": 100,
      "has_audio": true,
      "has_video": false,
      "duration_seconds": 45,
      "created_at": "2026-01-18T14:30:00.000Z",
      "completed_at": "2026-01-18T14:30:30.000Z"
    }
  ],
  "meta": {
    "total_count": 42,
    "has_more": true,
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0xN1QxMjowMDowMC4wMDBaIn0="
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:00.000Z"
}

Get Episode

GET/v1/episodes/{id}

Retrieves the current status and details of a specific episode. Use this endpoint to poll for completion of async episodes (video coming soon).

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Required	The unique identifier of the episode.

Query Parameters

Parameter	Type	Required	Description
`expand`	string	Optional	Comma-separated list of objects to expand. Currently supports "organization".

Response by Status

Processing

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "mode": "changelog",
    "source": "api",
    "progress_percent": 65,
    "current_stage": "audio_generation",
    "stages": ["pending", "script_generation", "audio_generation", "completed"],
    "estimated_completion_seconds": 15,
    "created_at": "2026-01-18T14:30:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:15.000Z"
}

Completed

Note: listen_url and embed_url appear when public_url: true was set.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "mode": "changelog",
    "source": "api",
    "audio_url": "https://api.logtalk.io/v1/episodes/550e8400.../audio",
    "video_url": null,
    "script": "[NARRATOR]: Welcome to Acme App...",
    "duration_seconds": 45,
    "listen_url": "https://logtalk.io/listen/550e8400-e29b-41d4-a716-446655440000",
    "embed_url": "https://logtalk.io/embed/550e8400-e29b-41d4-a716-446655440000",
    "completed_at": "2026-01-18T14:30:30.000Z",
    "created_at": "2026-01-18T14:30:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:30.000Z"
}

With expand=organization

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "mode": "changelog",
    "source": "api",
    "audio_url": "https://api.logtalk.io/v1/episodes/550e8400.../audio",
    "organization": {
      "id": "org_123e4567-e89b-12d3",
      "name": "Acme Corp",
      "logo_url": "https://example.com/logo.png",
      "created_at": "2026-01-01T00:00:00.000Z"
    },
    "completed_at": "2026-01-18T14:30:30.000Z",
    "created_at": "2026-01-18T14:30:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:30.000Z"
}

Failed

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "mode": "changelog",
    "source": "api",
    "error": {
      "code": "GENERATION_FAILED",
      "message": "Audio generation failed"
    },
    "failed_at": "2026-01-18T14:30:30.000Z",
    "created_at": "2026-01-18T14:30:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T14:30:30.000Z"
}

Retry a Failed Episode

POST/v1/episodes/{id}/retry

Retries a previously failed episode. Only episodes with status 'failed' can be retried. You can optionally override settings for the retry.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Required	The unique identifier of the failed episode to retry.

Request Body (Optional)

Parameter	Type	Required	Description
`override_settings`	object	Optional	Override episode settings for the retry. Uses original settings if not provided.
`webhook_url`	string	Optional	HTTPS URL to receive completion webhook notification.

Body

{
  "override_settings": {
    "tone": "professional"
  },
  "webhook_url": "https://example.com/webhooks/logtalk"
}

Delete Episode

DELETE/v1/episodes/{id}

Permanently deletes an episode and its associated media files. This action cannot be undone.

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Required	The unique identifier of the episode to delete.

200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "deleted": true,
    "deleted_at": "2026-01-18T15:00:00.000Z"
  },
  "request_id": "req_1kn5f2a_a3b4c5d6e7f8",
  "timestamp": "2026-01-18T15:00:00.000Z"
}

Request Headers

Optional headers that can be used with episode endpoints:

Header	Description
`X-Organization-ID`	Specify organization context for multi-org users. If omitted, uses the default organization for the API key.
`Idempotency-Key`	Unique key to prevent duplicate operations (POST endpoints only).

Idempotency

Use idempotency keys to safely retry requests without creating duplicate episodes. Include the Idempotency-Key header with a unique value:

curl -X POST https://api.logtalk.io/v1/episodes \
  -H "Authorization: Bearer lt_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-v2.0.0-20260118" \
  -d '{"content": "...", "output_format": "audio"}'

Keys must be 1-256 printable ASCII characters
Keys are valid for 24 hours
Retrying with the same key returns the cached response
Using the same key with a different request body returns 409 Conflict

When you create an episode with public_url: true, the response includes URLs for public sharing and embedding:

Field	Description
`listen_url`	Full public page with audio player, show notes, share buttons, and subscribe form.
`embed_url`	Compact player designed for iframe embedding on external sites.

Embedding with iframe

Use the embed_url to embed a compact audio player on your website:

<iframe
  src="https://logtalk.io/embed/550e8400-e29b-41d4-a716-446655440000"
  width="100%"
  height="180"
  frameborder="0"
  allow="autoplay"
></iframe>

oEmbed Support

LogTalk supports the oEmbed protocol for automatic embed discovery. Platforms like Notion, Medium, and others can automatically embed your episodes when you paste the listen_url.

oEmbed endpoint: https://logtalk.io/api/oembed?url={listen_url}

PreviousAuthentication NextScripts

Create an Episode

Request Body

Settings Object

Settings Object Reference

Body

Video Episode (Async)Coming Soon

List Episodes

Query Parameters

Get Episode

Path Parameters

Query Parameters

Response by Status

Processing

Completed

With expand=organization

Failed

Retry a Failed Episode

Path Parameters

Request Body (Optional)

Body

Delete Episode

Path Parameters

Request Headers

Idempotency

Public Sharing & Embedding

Embedding with iframe

oEmbed Support