We’re deprecating our legacy API at the end of Q2 2025.

To support this change, we’ve created a migration guide to help you update your integration. It includes example requests, responses and the steps needed to migrate.

If you’re currently using the legacy API, please read this migration guide to ensure continued functionality. You can find our most up-to-date API documentation here.

​
Updating your request header

Legacy APINew API
Base URLhttps://app.beyondwords.io/api/v4https://api.beyondwords.io/v1
Authentication header'Authorization''X-Api-Key'
Authentication valueYour API keyYour API key

​
Example requests

curl --request POST \
     --url https://api.beyondwords.io/v1 \
     --header 'X-Api-Key: <APIKEY>' \
     --header 'Content-Type: application/json' \

​
Key differences

  • Base URL: https://api.beyondwords.io/v1 (replaces https://app.beyondwords.io/api/v4)

  • Authentication: X-Api-Key (replaces Authorization header)

​
Endpoint and request body updates


Legacy APINew API
Endpoint/projects/{project_id}/audio/projects/{project_id}/content
Title FormatPlain textPlain text or HTML-formatted (e.g., <h1>Title</h1>) — HTML preferred.
Body FormatPlain textPlain text or HTML-formatted (e.g., <p>Body</p>) — HTML preferred.
Content ID HandlingSet using 'external_id'Set using 'source_id'

​
Example requests

curl --request POST \
     --url https://api.beyondwords.io/v1/projects/{project_id}/content \
     --header 'X-Api-Key: <APIKEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "type": "auto_segment",
  "title": "<h1>Title</h1>",
  "body": "<p>Example body text.</p>",
  "source_id": "<articleId>"
}'

These examples compare requests made using the Legacy APIs create endpoint with those using the new APIs create endpoint.

​
Example response

{
  "id": "744429b3-d77e-4230-b29f-c301f9da3bdd",
  "title": "title",
  "type": "auto_segment",
  "source_id": "<articleId>",
  "source_url": null,
  "published": true,
  "publish_date": "2025-03-12T16:28:19Z",
  "auto_segment_updates_enabled": true,
  "ai_summary_updates_enabled": true,
  "summary": null,
  "body": "example body text"
}
This is not a full response. It has been shortened to highlight the main differences. For more details on what a full response looks like, please visit our documentation.

​
Key differences

In the legacy API response, the returned ID is a numeric “podcast” id , which will no longer be used. In contrast, the new API returns a string content_id, which will remain the standard identifier moving forward.

While setting a source_id when creating content is optional, doing so eliminates the need to store the content_id from the response. Without a source_id, you may need to save the content_id separately to embed the player. By setting the source_id as the article ID you may have already set, you can easily use this to embed the BeyondWords player without additional data handling.

​
Migration steps

1

Update the base URL

  • Change all API requests from: https://app.beyondwords.io/api/v4
  • To: https://api.beyondwords.io/v1
    Search your codebase for the legacy URL to find all instances
2

Update request header method

  • Legacy API: Uses the Authorization header with the API key.
  • New API: Requires the X-Api-Key header with the API key.
  • Note: The API key value itself remains the same
3

Update endpoints

Replace old API endpoints with the new ones:

  • Legacy API: /projects/{project_id}/audio
  • New API: /projects/{project_id}/content
  • Also update: Any other endpoints you’re using (see our full documentation)
4

Handle ID changes

  • Legacy API: Returns a numeric “podcast” id (deprecated).
  • New API: Returns a string-based UUID “content” id.
  • Action required: Update any code that expects or processes the ID
5

Use source_id for easier integration

  • Change field name from external_id to source_id in your requests
  • Setting a source_id when creating content is optional but recommended
  • If you set source_id to match your existing article ID, you can use it to embed the BeyondWords player without needing to store the content_id from the response
6

Update Content Format (Optional)

  • Consider using HTML formatting for title and body content
  • Example: "title": "<h1>Title</h1>" instead of "title": "Title"
  • This provides better control over how content is processed

​
FAQ

Q: Will my existing API key still work?
A: Yes, your API key will continue to work. Only the header name and endpoints are changing.

Q: What happens if I don’t migrate by the deadline?
A: After Q2 2025, the legacy API will be shut down and any applications using it will receive errors.

Q: Can I use both APIs during the transition period?
A: Yes, both APIs will be available until the deprecation date to allow for a smooth transition.

📖 For full details, refer to our API documentation.
💬 If you need further support, reach out on Slack or contact support@beyondwords.io.

​
Summary of key changes

FeatureLegacy APINew APINotes
Base URLhttps://app.beyondwords.io/api/v4https://api.beyondwords.io/v1All endpoints use the new base URL
AuthenticationAuthorization headerX-Api-Key headerSame API key, different header name
Content creation/projects/{project_id}/audio/projects/{project_id}/contentEndpoint name change
Content identifierNumeric idString UUID idFormat change for BeyondWords content ID
Article identifierexternal_idsource_idField name change (both string format)
Content formatPlain text onlyPlain text or HTML (preferred)Enhanced formatting options

Remember to update all instances where your application interacts with our API, including scheduled jobs, error handling, and any third-party integrations.