Migrate from legacy API to current version
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 |
https://api.beyondwords.io/v1
(replaces https://app.beyondwords.io/api/v4
)
X-Api-Key
(replaces Authorization
header)
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' |
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.
Update the base URL
https://app.beyondwords.io/api/v4
https://api.beyondwords.io/v1
Update request header method
Authorization
header with the API key.X-Api-Key
header with the API key.Update endpoints
/projects/{project_id}/audio
/projects/{project_id}/content
Handle ID changes
Use source_id for easier integration
external_id
to source_id
in your requestssource_id
when creating content is optional but recommendedsource_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 responseUpdate Content Format (Optional)
"title": "<h1>Title</h1>"
instead of "title": "Title"
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 |