​

BeyondWords API overview

The BeyondWords API is a RESTful API that provides headless access to the entire platform, allowing you to programmatically create, manage, and deliver audio content.

​

API basics

• Base URL: https://api.beyondwords.io/
• Format: The API accepts form-encoded request bodies and returns JSON-encoded responses
• Design: Uses predictable resource-oriented URLs and standard HTTP methods
• Status Codes: Uses standard HTTP response codes to indicate success or failure

​

Authentication

All API requests require authentication using your Project ID and API Key.

​

Obtaining credentials

1. Create a BeyondWords account
2. Create a project in the dashboard
3. Navigate to Settings > Integrations > API to find your Project ID and API Key

​

Security best practices

• Your API key carries many privileges, so be sure to safeguard it
• Never share your API key in publicly accessible places such as client-side code or GitHub
• Consider using environment variables to store your API credentials

​

Authentication methods

Most endpoints require the X-Api-Key header for authentication:

# API request example
curl -X GET "https://api.beyondwords.io/v1/endpoint" \
  -H "X-Api-Key: YOUR_API_KEY"

Most endpoints also require your Project ID, which is typically included as a path parameter. Each endpoint in this documentation will clearly indicate whether a Project ID is required.

​

Request guidelines

• All API requests must use HTTPS; requests over plain HTTP will fail
• Requests without proper authentication will be rejected with a 401 Unauthorized response
• Include a content-type header of application/json for requests with JSON bodies

​

Versioning

The API uses versioned endpoints to ensure compatibility:

• Current stable version: v1
• Include the version in the URL path: https://api.beyondwords.io/v1/endpoint

​

Error handling

The API uses conventional HTTP response codes:

• 2xx - Success
• 4xx - Client errors (invalid request)
• 5xx - Server errors

Error responses include a JSON body with details:

{
  "error": {
    "code": "invalid_request",
    "message": "A detailed error message",
    "details": { /* Additional context */ }
  }
}

​

Getting help

If you encounter issues or have questions:

• Contact support@beyondwords.io