Skip to main content
The BeyondWords API is a RESTful API that provides headless access to the entire platform. Use it to send content from your CMS or backend, retrieve player data, and manage your project programmatically.

API reference

Curated reference for content, distribution, integrations, analytics, and organization endpoints.

Full reference

Complete endpoint catalog, including admin, voice cloning, and advanced configuration APIs.

​
Typical integration flow

1

Get your credentials

Go to Settings → Integrations → API in your project dashboard to find your Project ID and API Key.
2

Create or update content

Use the API to create and update content items from your CMS or backend. Set a source_id to your CMS article ID when creating content—this is optional but recommended. If you’re sending HTML or source URLs, see content extraction for how BeyondWords processes page content.
3

Install the player

Unlike the Magic Embed, WordPress, and Ghost integrations, the API does not install the player automatically. Install the player separately on your website or app using the JavaScript, iOS, or Android SDK.
4

Listen for changes (optional)

Use webhooks to receive notifications when content is created, updated, or deleted, rather than polling the API.
Migrating from the legacy v4 API? See the API migration guide.

​
Base URL

All requests use HTTPS. The current stable version is v1: 
https://api.beyondwords.io/v1/

​
Authentication

All API requests require your Project ID and API Key. Include your API key as a header on every request. Your Project ID is typically included as a path parameter (as in the example below). 
curl -X GET "https://api.beyondwords.io/v1/projects/YOUR_PROJECT_ID/content" \
  -H "X-Api-Key: YOUR_API_KEY"
Requests without valid authentication are rejected with a 401 Unauthorized response.
Keep your API key secret. Never expose it in client-side code or public repositories. Use environment variables to store credentials securely.

​
Request format

The API uses JSON for both requests and responses. Send request bodies as JSON with a Content-Type: application/json header. File uploads are the exception—they use multipart/form-data.

​
Core resources

The API provides access to several resources. The primary ones include:

​
Projects

This object represents your BeyondWords project and its settings. See Projects in the API reference.

​
Content

This object represents your generated content and its associated metadata. You can list, create, retrieve, update, and delete content, and regenerate or upload audio. When creating content, publishers are encouraged to include a source_id—your own identifier for the article, such as your CMS article ID. This is optional, but avoids having to store the content_id returned by the API. You can then load the player using sourceId instead of contentId, which simplifies integration when you already have an article ID in your system. See Generating content in the API reference. Related sections cover extraction, pronunciation settings, script settings, video settings, and background music settings.

​
Voices

List, create, and manage organization voices, speakers, and languages.

​
Player

Retrieve audio, video, and player configuration using identifiers such as Content ID, Source ID, Source URL, or Playlist ID. If you set a source_id when creating content, get player by source ID is often the simplest way to embed the player—you can use the same ID your CMS already knows.

​
Playlists

BeyondWords supports three playlist types. Only standard and smart playlists are created and managed through the API—dynamic playlists are built client-side in the player and are not API resources.
TypeAPI typeUse caseHow to create
StandardmanualFixed editorial collections—daily roundups, story packages, or any hand-picked set of contentCreate playlist with type: "manual" and a list of content IDs
SmartautoAutomatically updating feeds—e.g., all articles by an author, or all content matching a topicCreate playlist with type: "auto" and filtering rules
Dynamic—User-curated queues—e.g., an “add to queue” feature where visitors build their own playlistNot via the API. Pass an array of content identifiers to the player’s playlist property. See dynamic playlists.
To load a standard or smart playlist in the player, use its playlistId with get player by playlist ID. For dynamic playlists, use the JavaScript player SDK directly. Standard and smart playlist endpoints: See Player and Player settings in the API reference.

​
Distribution

Beyond the player endpoints, you can manage playlists, access tiers, and podcast feed settings via the API.

​
Integrations

Use Webhooks to receive HTTP notifications when content is created, updated, or deleted. See the Webhooks guide for setup instructions. Import content from external RSS feeds via the RSS feed importer. See the RSS feed importer guide. Configure Magic Embed via the Magic Embed API. See the Magic Embed guide. Connect Ghost via the Ghost integration API. See the Ghost guide.

​
Analytics

Retrieve analytics for an organization, project, content item, or ad. Filter by time period and aggregate by year, month, week, day, or hour. See Analytics in the API reference.

​
Monetization

Manage ads via the API.

​
Error handling

The API uses standard HTTP response codes:
  • 2xx—Success
  • 4xx—Client error (check your request)
  • 5xx—Server error
Error responses include a JSON body with details: 
{
  "error": {
    "code": "invalid_request",
    "message": "A detailed error message",
    "details": {}
  }
}

​
Getting help

If you encounter issues or have questions, contact support.