> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

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.

<CardGroup cols={2}>
  <Card title="API reference" icon="code" href="/api-reference/overview">
    Curated reference for content, distribution, integrations, analytics, and organization endpoints.
  </Card>

  <Card title="Full reference" icon="rectangle-terminal" href="/full-api-reference">
    Complete endpoint catalog, including admin, voice cloning, and advanced configuration APIs.
  </Card>
</CardGroup>

## Typical integration flow

<Steps>
  <Step title="Get your credentials">
    Go to **Settings → Integrations → API** in your [project dashboard](/docs-and-guides/get-started/projects) to find your **Project ID** and **API Key**.
  </Step>

  <Step title="Create or update content">
    Use the API to [create](/api-reference/content/create) and [update](/api-reference/content/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](/docs-and-guides/integrations/content-extraction) for how BeyondWords processes page content.
  </Step>

  <Step title="Install the player">
    Unlike the Magic Embed, WordPress, and Ghost integrations, the API does not install the player automatically. [Install the player](/docs-and-guides/distribution/player/player-introduction) separately on your website or app using the [JavaScript](/docs-and-guides/distribution/player/installation/javascript-sdk), [iOS](/docs-and-guides/distribution/player/installation/ios-sdk), or [Android](/docs-and-guides/distribution/player/installation/android-sdk) SDK.
  </Step>

  <Step title="Listen for changes (optional)">
    Use [webhooks](/docs-and-guides/integrations/webhooks) to receive notifications when content is created, updated, or deleted, rather than polling the API.
  </Step>
</Steps>

<Tip>
  Migrating from the legacy v4 API? See the [API migration guide](/docs-and-guides/migration-guides/api-legacy).
</Tip>

## Base URL

All requests use HTTPS. The current stable version is `v1`:

```text theme={null}
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).

```bash theme={null}
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.

<Warning>
  Keep your API key secret. Never expose it in client-side code or public repositories. Use environment variables to store credentials securely.
</Warning>

## 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.

* [List projects](/api-reference/projects/list)
* [Create project](/api-reference/projects/create)
* [Get project](/api-reference/projects/show)
* [Update project](/api-reference/projects/update)
* [Delete project](/api-reference/projects/delete)
* [Get project voices](/api-reference/projects/voices)

See [Projects](/api-reference/projects/list) 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](/api-reference/content/create), 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.

* [List content](/api-reference/content/list)
* [Create content](/api-reference/content/create)
* [Get content](/api-reference/content/show)
* [Update content](/api-reference/content/update)
* [Delete content](/api-reference/content/delete)
* [Regenerate content](/api-reference/content/regenerate)

See [Generating content](/api-reference/content/introduction) in the API reference. Related sections cover [extraction](/api-reference/content-filters/overview), [pronunciation settings](/api-reference/rules/list), [script settings](/api-reference/summarization-settings/show), [video settings](/api-reference/video-settings/show), and [background music settings](/api-reference/background-tracks/list).

### Voices

List, create, and manage organization [voices](/api-reference/voices/list), [speakers](/api-reference/speakers/list), and [languages](/api-reference/languages/list).

### 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](/api-reference/player/show-2) is often the simplest way to embed the player—you can use the same ID your CMS already knows.

* [Get player by content ID](/api-reference/player/show)
* [Get player by playlist ID](/api-reference/player/show-1)
* [Get player by source ID](/api-reference/player/show-2)
* [Get player by source URL](/api-reference/player/show-3)
* [Get player by multiple identifiers](/api-reference/player/show-4)

### Playlists

BeyondWords supports three [playlist](/docs-and-guides/distribution/playlists) 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.

| Type         | API type | Use case                                                                                      | How to create                                                                                                                                                                                                                                                                    |
| ------------ | -------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Standard** | `manual` | Fixed editorial collections—daily roundups, story packages, or any hand-picked set of content | [Create playlist](/api-reference/playlists/create) with `type: "manual"` and a list of content IDs                                                                                                                                                                               |
| **Smart**    | `auto`   | Automatically updating feeds—e.g., all articles by an author, or all content matching a topic | [Create playlist](/api-reference/playlists/create) with `type: "auto"` and filtering rules                                                                                                                                                                                       |
| **Dynamic**  | —        | User-curated queues—e.g., an "add to queue" feature where visitors build their own playlist   | Not via the API. Pass an array of content identifiers to the player's [`playlist`](/docs-and-guides/distribution/player/developer-guides/player-properties#param-playlist) property. See [dynamic playlists](/docs-and-guides/distribution/playlists#create-a-dynamic-playlist). |

To load a standard or smart playlist in the player, use its `playlistId` with [get player by playlist ID](/api-reference/player/show-1). For dynamic playlists, use the [JavaScript player SDK](/docs-and-guides/distribution/player/installation/javascript-sdk) directly.

**Standard and smart playlist endpoints:**

* [List playlists](/api-reference/playlists/list)
* [Create playlist](/api-reference/playlists/create)
* [Get playlist](/api-reference/playlists/show)
* [Update playlist](/api-reference/playlists/update)
* [Delete playlist](/api-reference/playlists/delete)
* [Get playlist settings](/api-reference/playlists/show-1)
* [Update playlist settings](/api-reference/playlists/update-1)

See [Player](/api-reference/player/by-content-id) and [Player settings](/api-reference/player-settings/show) in the API reference.

### Distribution

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

* [Playlists](/api-reference/playlists/list)
* [Access tiers](/api-reference/access-tiers/list)
* [Podcast feeds](/api-reference/podcast-feeds/get-settings)

### Integrations

Use [Webhooks](/api-reference/webhooks/list) to receive HTTP notifications when content is created, updated, or deleted. See the [Webhooks guide](/docs-and-guides/integrations/webhooks) for setup instructions.

Import content from external RSS feeds via the [RSS feed importer](/api-reference/rss-feed-importer/list). See the [RSS feed importer guide](/docs-and-guides/integrations/rss-feed-importer).

Configure Magic Embed via the [Magic Embed API](/api-reference/magic-embed/show). See the [Magic Embed guide](/docs-and-guides/integrations/magic-embed).

Connect Ghost via the [Ghost integration API](/api-reference/ghost/show). See the [Ghost guide](/docs-and-guides/integrations/publishing-platforms/ghost).

### Analytics

Retrieve analytics for an organization, project, content item, or ad. Filter by time period and aggregate by year, month, week, day, or hour.

* [Get organization analytics](/api-reference/analytics/organization-analytics)
* [List projects analytics](/api-reference/analytics/projects-analytics)
* [Get project analytics](/api-reference/analytics/project-analytics)
* [List content analytics](/api-reference/analytics/contents-analytics)
* [Get content analytics](/api-reference/analytics/content-analytics)
* [List ads analytics](/api-reference/analytics/ads-analytics)
* [Get ad analytics](/api-reference/analytics/ad-analytics)

See [Analytics](/api-reference/analytics/organization-analytics) in the API reference.

### Monetization

Manage [ads](/api-reference/ads/list) 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:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "A detailed error message",
    "details": {}
  }
}
```

## Getting help

If you encounter issues or have questions, [contact support](/docs-and-guides/support/get-support).