Get website configuration

GET

/v2/config

curl https://texttospeech.responsivevoice.org/v2/config -H 'X-API-Key: YOUR_API_KEY' -H 'X-API-Secret: YOUR_API_SECRET'

• Production

Returns the website configuration including feature flags and voice settings for the authenticated user. Free-tier users receive all defaults (all features disabled, default voice). Commercial and admin users receive their stored dashboard settings merged with defaults. Feature flags control JS dashboard plugins: welcomeMessage (speaks a greeting on page load), speakSelectedText (reads highlighted text aloud), speakLinks (reads link text on hover), speakInactivity (speaks after a period of user inactivity), speakEndPage (speaks when user scrolls to page bottom), exitIntent (speaks when user moves cursor to leave the page), accessibilityNavigation (keyboard tab navigation with speech), paragraphNavigation (keyboard paragraph-by-paragraph navigation with speech).

Authorizations

• apiKeyHeader
• apiSecretHeader

Responses

200

Website configuration with feature flags, voice settings (name, pitch, rate, volume), and analytics toggle. Free-tier users get all features disabled; paid users get their stored dashboard configuration.

Media type application/json

object

features

object

welcomeMessage

object

enabled

boolean

text

string | null

speakSelectedText

object

enabled

boolean

speakLinks

object

enabled

boolean

speakInactivity

object

enabled

boolean

text

string | null

speakEndPage

object

enabled

boolean

text

string | null

exitIntent

object

enabled

boolean

text

string | null

accessibilityNavigation

object

enabled

boolean

paragraphNavigation

object

enabled

boolean

webPlayer

object

enabled

boolean

selector

string

default: article

paragraphSelector

string

default: p, h2, h3, li

position

Any of:

string

string

Allowed values: inline before after

object

object

target

required

string

at

string

default: inside

Allowed values: inside before after

theme

Any of:

string

string

Allowed values: neutral responsivevoice

object

object

bg

string

fg

string

muted

string

accent

string

accentSoft

string

hover

string

border

string

track

string

fill

string

controls

object

progress

boolean

default: true

time

boolean

default: true

skip

boolean

default: true

speed

boolean

default: true

brand

boolean

default: true

navigation

object

paragraphHighlight

boolean

default: true

paragraphClick

boolean

default: true

layout

object

mode

string

default: shrink

Allowed values: shrink fill

display

string

default: block

Allowed values: inline block

miniPlayer

object

enabled

boolean

default: true

position

Any of:

string

string

Allowed values: top-left top-right bottom-left bottom-right

object

object

top

string

right

string

bottom

string

left

string

animation

string

default: slide

Allowed values: none fade slide pop

voice

Any of:

string

string

object

object

regex

required

string

flags

string

object

object

name

string

lang

string

gender

string

Allowed values: f m male female

isByok

boolean

provider

string

sanitize

object

enabled

boolean

default: true

exclude

Array<string>

default:

pitch

number

<= 2

rate

number

<= 2

volume

number

<= 1

welcomeMessageOnce

boolean

voice

object

name

string

default: UK English Female

pitch

number

default: 1 <= 2

rate

number

default: 1 <= 2

volume

number

default: 1 <= 1

analytics

object

enabled

boolean

Example

{
  "features": {
    "welcomeMessage": {
      "enabled": false,
      "text": null
    },
    "speakSelectedText": {
      "enabled": false
    },
    "speakLinks": {
      "enabled": false
    },
    "speakInactivity": {
      "enabled": false,
      "text": null
    },
    "speakEndPage": {
      "enabled": false,
      "text": null
    },
    "exitIntent": {
      "enabled": false,
      "text": null
    },
    "accessibilityNavigation": {
      "enabled": false
    },
    "paragraphNavigation": {
      "enabled": false
    },
    "webPlayer": {
      "enabled": false,
      "selector": "article",
      "paragraphSelector": "p, h2, h3, li",
      "position": "before",
      "theme": "neutral",
      "controls": {
        "progress": true,
        "time": true,
        "skip": true,
        "speed": true,
        "brand": true
      },
      "navigation": {
        "paragraphHighlight": true,
        "paragraphClick": true
      },
      "layout": {
        "mode": "shrink",
        "display": "block"
      },
      "miniPlayer": {
        "enabled": true,
        "position": "bottom-left",
        "animation": "slide"
      },
      "sanitize": {
        "enabled": true,
        "exclude": []
      }
    },
    "welcomeMessageOnce": false
  },
  "voice": {
    "name": "UK English Female",
    "pitch": 1,
    "rate": 1,
    "volume": 1
  },
  "analytics": {
    "enabled": false
  }
}

Headers

X-RateLimit-Limit

required

Maximum requests permitted for the authenticated key per minute.

integer

Maximum requests permitted for the authenticated key per minute.

X-RateLimit-Remaining

required

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

integer

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

401

API key required — all config requests must be authenticated

Media type application/json

API error response

object

error

required

object

message

required

string

code

string

statusCode

required

number

errors

Example ^generated

{
  "error": {
    "message": "example",
    "code": "example",
    "statusCode": 1,
    "errors": "example"
  }
}

429

Rate limit exceeded. The body code is RATE_LIMIT_EXCEEDED (per-minute tier limit) or BURST_RATE_LIMIT_EXCEEDED (per API key + client IP burst).

Media type application/json

API error response

object

error

required

object

message

required

string

code

string

statusCode

required

number

errors

Example ^generated

{
  "error": {
    "message": "example",
    "code": "example",
    "statusCode": 1,
    "errors": "example"
  }
}

Headers

X-RateLimit-Limit

required

Maximum requests permitted for the authenticated key per minute.

integer

Maximum requests permitted for the authenticated key per minute.

X-RateLimit-Remaining

required

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

integer

Requests remaining in the current per-minute window; 0 once the per-minute limit is reached. Reflects the per-minute limit, not the burst check — a burst 429 may report a value above 0.

Retry-After

required

Seconds to wait before retrying. Dynamic — varies with how far over the limit the request went; honor this header rather than assuming a fixed delay.

integer

Seconds to wait before retrying. Dynamic — varies with how far over the limit the request went; honor this header rather than assuming a fixed delay.