Skip to main content
The BeyondWords API is a RESTful API that provides headless access to the entire platform. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. This reference covers the endpoints most integrators need.

​
Base URL

All requests use the v1 API. Prepend this base URL to every endpoint path: 
https://api.beyondwords.io/v1/
For example, listing content items for a project: 
https://api.beyondwords.io/v1/projects/{project_id}/content
Replace {project_id} with your Project ID from Settings → Integrations → API in the dashboard.

​
Authentication

Every request requires your API key in the X-Api-Key header. Find your Project ID and API Key under Settings → Integrations → API. 
-H "X-Api-Key: YOUR_API_KEY"
Keep your API key secret. Do not expose it in client-side code or public repositories.

​
Rate limits

To help keep our service stable and reliable, API requests are subject to the following rate limits:
Request typeLimit
GET requests100 requests per 60 seconds
All other requests25 requests per 60 seconds

​
Handling rate limits

Design your integration to avoid exceeding these limits. We recommend implementing client-side rate limiting so requests are spread evenly over time rather than sent in large bursts. If your application receives a 429 Too Many Requests response, it should wait before retrying the request. We recommend retrying after approximately 30 seconds. To avoid unnecessary API usage and improve reliability:
  • Do not continuously poll API endpoints for status updates.
  • Use webhooks where possible, especially for status or state-change events.
  • Add a global concurrency limit across your application, not just per worker or per process.
  • Cache GET responses where appropriate.
  • Avoid running multiple parallel jobs that may unintentionally create request spikes.
Following these practices will help your integration remain reliable and avoid temporary throttling.

​
Resources

​
Content

Content items are the core resource. See the developer guide for processing types, the content object, and syndication. Example: create content with auto_segment Send title as plain text. body should be HTML. 
curl -X POST "https://api.beyondwords.io/v1/projects/{project_id}/content" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "auto_segment",
    "title": "Article title",
    "body": "<p>First paragraph.</p><p>Second paragraph.</p>",
    "source_id": "cms-article-123",
    "source_url": "https://example.com/article"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "type": "auto_segment",
  "title": "Article title",
  "body": "<p>First paragraph.</p><p>Second paragraph.</p>",
  "source_id": "cms-article-123",
  "source_url": "https://example.com/article",
  "published": true,
  "segments": [],
  "audio": [],
  "video": [],
  "created": "2025-06-08T10:00:00.000Z",
  "updated": "2025-06-08T10:00:00.000Z"
}
Set up webhooks to be notified when processing completes. See the Webhooks guide for setup. Endpoints

​
Extraction

Control how text is extracted from webpages when ingesting content. Filters Extraction settings

​
Pronunciation settings

​
Script settings

Script templates

​
Video settings

Video templates

​
Background music settings

​
Voices

Voices Voice generation Speakers Voice cloning Languages

​
Distribution

Player Player settings Access tiers Playlists Podcast feeds

​
Integrations

Webhooks RSS feed importer Magic Embed Ghost

​
Analytics

Content Ads

​
Monetization

Ads

​
Organization

Projects