> ## 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 (Legacy)

> Migrate from legacy API to current version

We're deprecating our legacy API at the end of Q2 2025.

To support this change, we've created a migration guide to help you update your integration. It includes example requests, responses and the steps needed to migrate.

If you're currently using the legacy API, please read this migration guide to ensure continued functionality. You can find our most up-to-date API documentation [here](/api-reference/overview).

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

<CodeGroup>
  ```javascript New API theme={null}
  curl --request POST \
       --url https://api.beyondwords.io/v1 \
       --header 'X-Api-Key: <APIKEY>' \
       --header 'Content-Type: application/json' \
  ```

  ```javascript Legacy API theme={null}
  curl -L \
    --request POST \
    --url 'https://app.beyondwords.io/api/v4' \
    --header 'Authorization: <APIKEY>' \
    --header 'Content-Type: application/json' \

  ```
</CodeGroup>

### Key differences

* Base URL: `https://api.beyondwords.io/v1` (replaces `https://app.beyondwords.io/api/v4`)

* Authentication: `X-Api-Key` (replaces `Authorization` header)

## Endpoint and request body updates

<br />

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

<CodeGroup>
  ```javascript New API theme={null}
  curl --request POST \
       --url https://api.beyondwords.io/v1/projects/{project_id}/content \
       --header 'X-Api-Key: <APIKEY>' \
       --header 'Content-Type: application/json' \
       --data '
  {
    "type": "auto_segment",
    "title": "<h1>Title</h1>",
    "body": "<p>Example body text.</p>",
    "source_id": "<articleId>"
  }'
  ```

  ```javascript Legacy API theme={null}
  curl -L \
    --request POST \
    --url 'https://app.beyondwords.io/api/v4/projects/{project_id}/audio' \
    --header 'Authorization: <API KEY>' \
    --header 'Content-Type: application/json' \
    --data '
  {
    "title":"Title",
    "body":"Example body text.",
    "external_id":"<articleId>"
  }'
  ```
</CodeGroup>

These examples compare requests made using the Legacy APIs create endpoint  with those using the new APIs create endpoint.

### Example response

<CodeGroup>
  ```javascript New API theme={null}
  {
    "id": "744429b3-d77e-4230-b29f-c301f9da3bdd",
    "title": "title",
    "type": "auto_segment",
    "source_id": "<articleId>",
    "source_url": null,
    "published": true,
    "publish_date": "2025-03-12T16:28:19Z",
    "auto_segment_updates_enabled": true,
    "ai_summary_updates_enabled": true,
    "summary": null,
    "body": "example body text"
  }
  ```

  ```javascript Legacy API theme={null}
  {
    "id": 15312327,
    "title": "Title",
    "external_id": "<articleId>",
    "state": "unprocessed",
    "metadata": {
      "key": "value"
    },
    "media": [],
    "image_url": null,
    "deleted": false,
    "access_key": null,
    "processing_at": "2025-02-18T16:33:35.537Z",
    "published": true,
    "published_at": "2025-02-18T16:33:35.315Z",
    "source_id": "<externallySetID>"
  }
  ```
</CodeGroup>

<Info>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](#).</Info>

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

## Migration steps

<Steps>
  <Step title="Update the base URL">
    * Change all API requests from: `https://app.beyondwords.io/api/v4`
    * To: `https://api.beyondwords.io/v1`
      <Tip>Search your codebase for the legacy URL to find all instances</Tip>
  </Step>

  <Step title="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
  </Step>

  <Step title="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](#))
  </Step>

  <Step title="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
  </Step>

  <Step title="Use source_id for easier integration">
    * Change field name from `external_id` to `source_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
  </Step>

  <Step title="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
  </Step>
</Steps>

## 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](/api-reference/overview).\
💬 If you need further support, reach out on Slack or contact [support@beyondwords.io](mailto: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              |

<Warning>
  Remember to update all instances where your application interacts with our API, including scheduled jobs, error handling, and any third-party integrations.
</Warning>