Updating your request header
Legacy API | New API | |
---|---|---|
Base URL | https://app.beyondwords.io/api/v4 | https://api.beyondwords.io/v1 |
Authentication header | 'Authorization' | 'X-Api-Key' |
Authentication value | Your API key | Your API key |
Example requests
Key differences
-
Base URL:
https://api.beyondwords.io/v1
(replaceshttps://app.beyondwords.io/api/v4
) -
Authentication:
X-Api-Key
(replacesAuthorization
header)
Endpoint and request body updates
Legacy API | New API | |
---|---|---|
Endpoint | /projects/{project_id}/audio | /projects/{project_id}/content |
Title Format | Plain text | Plain text or HTML-formatted (e.g., <h1>Title</h1> ) — HTML preferred. |
Body Format | Plain text | Plain text or HTML-formatted (e.g., <p>Body</p> ) — HTML preferred. |
Content ID Handling | Set using 'external_id' | Set using 'source_id' |
Example requests
Example response
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 stringcontent_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
tosource_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
Feature | Legacy API | New API | Notes |
---|---|---|---|
Base URL | https://app.beyondwords.io/api/v4 | https://api.beyondwords.io/v1 | All endpoints use the new base URL |
Authentication | Authorization header | X-Api-Key header | Same API key, different header name |
Content creation | /projects/{project_id}/audio | /projects/{project_id}/content | Endpoint name change |
Content identifier | Numeric id | String UUID id | Format change for BeyondWords content ID |
Article identifier | external_id | source_id | Field name change (both string format) |
Content format | Plain text only | Plain 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.