Skip to main content

​
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 project in the dashboard
  2. 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: