Developer API

Manage your account using Wordly’s REST APIs

You can now manage your account using Wordly’s REST APIs. You can view the OpenAPI documentation and try out the APIs yourself over at the API Reference page provided that you have a developer API key.

Please note that the API Reference page acts on live data, so be cautious when using it.

New features will be added regularly, so stay tuned for more updates!


Click here to view the changelog.

Getting a Developer API Key

A developer API key must be included as a header for all requests. You must have a Wordly account, and your account must be added to an allow list before you can create and use an API key. You can request to have your account added by contacting Wordly Support.

Once your account has been added to the allow list, you can create a non-expiring API key in the Portal by following these steps:

  1. Go to your user profile page in the Wordly Portal.
  2. Click on the ‘+’ icon button in the API Key row to create a new API key. Creating an API Key

If you do not see the API Key row in your profile, then your account has not been added to the allow list.

Getting Started

The following section will help get you started in using Wordly’s REST APIs. You can view the Open API documentation and try out the API yourself over at

Authorization Header

In order to use the API, you must include the x-wordly-api-key header with every request. The value of this header is your developer API key.

Example: x-wordly-api-key: f716690b-4e9a-4656-9523-7003637eb6cc

Failure to provide the API key in the header will result in a 401 (i.e., unauthorized) response from the server.


As new versions of the API are released, the request and response body schemas may change.

Wordly will include the x-wordly-api-version header in every response which tells you which version of the API the response body is conforming to.

Example: x-wordly-api-version: 1.0

Conversely, you can provide the x-wordly-api-version header in your requests to pin the request and response body schema to a specific API version. This ensures that your requests will continue to work when new versions of the API are released.

If you do not provide the x-wordly-api-version header in your requests, then Wordly will assume the latest API version. Therefore, we strongly recommend that you include this header with every request.


If an error occurs while processing your request, you will receive an HTTP error response. In most cases, you will receive a JSON response body in the following format:

  "message": "An error message will be here.",
  "code": 2003,
  "errors": [
      "message": "Any additional error information..."
      "message": "...will be listed here."

The code field is a numeric error code that is specific to Wordly. The table below is a list of possible error codes that you may receive in an error response.

Error Code Description
2003 Not authorized to perform this action.
2026 A field is not valid.
2041 Operation cannot be completed because the session is in use.
5001 Required fields are missing from the request.
5002 A field is not valid.
5004 Requested resource could not be found.

Deleting a Developer API Key

If you wish to delete and revoke your API key, then you can do so through the Portal. You are free to generate a new API key after deleting your existing one.

Follow these steps to delete your API key:

  1. Go to your user profile page in the Wordly Portal.
  2. Click on the trashcan icon button in the API Key row to delete your API key. Deleting an API Key


Caption Webhook Request Body

The Captions API allows an ongoing Wordly session to send live captions to a designated webhook URL. Captions will continue to be generated and sent until the Wordly session ends or until captioning is explicily stopped using the API.

A webhook URL must be provided when making the request to start captioning a Wordly session. As Wordly generates caption segments, they will be sent to the webhook URL via a POST request.

The body of this POST request will be a single JSON object that contains the following fields.

JSON Field Type Description
sequence number

The sequence number for this caption segment which defines the order that captions should be shown starting with 1. This will always be set to the correct value by the service, and caption segments will be sent to the webhook URL in this order.

Generally, caption segments will also arrive in order; however, be aware that this is not a guarantee due to network conditions outside of Wordly’s control. Therefore, the sequence number can be used to verify the ordering of captions segments as they arrive.

language string A Wordly language code. The caption text will be in this language.
text string The actual caption text formatted as specified per the caption settings that were provided when captioning was requested.
duration number How long the caption should be displayed in milliseconds.

Voice Pack IDs

Sessions can be assigned a voice pack ID. A voice pack is a curated, one-to-one mapping of voices to available Wordly attendee languages. Attendees using the Wordly Web Attend app will hear transcriptions and translations using the voices in the specified pack if they elect to use the speak along feature.

Currently, there is no way to programmatically retrieve a list of available voice packs. However, the following curated voice packs can be used when specifying the voice pack ID for a session.

Voice Pack Name Voice Pack ID
Voice Pack 1 672def43-f760-451c-82f8-c01711ccaa84
Voice Pack 2 97cc30b9-a883-47d5-a2d1-0ad89fc69187

If you do not specify a voice pack when creating a session using the API, then the created session will use the voice pack selected in your Wordly profile. By default, your profile will be set to use the default voice pack, which is currently Voice Pack 1.

You can sample the voice packs for different languages when editing a session or updating your profile in the Wordly Portal.


Notable changes made to the Wordly API