API reference
Provider credentials
Bring your own provider accounts (model, voice and telephony providers). Secrets are encrypted at rest and never returned.
List provider credentials
GET/api/integrations
Which providers have a credential stored for the project (model, speech and telephony providers), with when it was saved; the secrets themselves are never returned. Credentials belong to one project; an org-wide key must name project_id.
Secret API key. How it works
Query parameters
project_idstringThe project. Required with an org-wide key.
Returns
200 OK
Response attributes
dataarray of Integrationrequired5 attributes
providerstringrequiredProvider slug, e.g. openai, perplexity, deepgram, elevenlabs, twilio.
key_versionintegerrequiredMaster-key version the secret is sealed under.
created_atstringrequiredISO 8601 timestampupdated_atstringrequiredISO 8601 timestamphealthIntegrationHealthrequiredHow the key fared on the latest model calls made with it. Saving a new key starts it again at
unknown. Health reflects calls made by Search only for now, so a key used only by chat readsunknown.4 attributes
statusstringrequiredok: the latest call worked.failing: the latest call was refused because the key was rejected or the account is out of credit, and nothing has worked since.degraded: the latest call failed for a passing reason (rate limit, provider down, or unclassified).unknown: no model call recorded yet.One of
okfailingdegradedunknownlast_success_atstring | nullrequiredISO 8601 timestamplast_failure_atstring | nullrequiredISO 8601 timestamplast_failure_kindstring | nullrequiredWhy the latest failure happened. Kept after a later success, so read it with
status.One of
invalid_keyout_of_creditrate_limitedprovider_unavailableunknown
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl "https://api.brightshoal.com/api/integrations" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": [
{
"provider": "string",
"key_version": 1,
"created_at": "2026-10-28T09:30:00.000Z",
"updated_at": "2026-10-28T09:30:00.000Z",
"health": {
"status": "ok",
"last_success_at": "2026-10-28T09:30:00.000Z",
"last_failure_at": "2026-10-28T09:30:00.000Z",
"last_failure_kind": "invalid_key"
}
}
]
}Save a provider credential
PUT/api/integrations/{provider}
Saves your own account's key for a provider, so assistants in the project run on it. It is stored encrypted and never returned. Where the provider can be checked, the key is tried first and a refused key is not stored (422). verified: false means it could not be checked; it is stored anyway.
Secret API key, not a viewer key. How it works
Path parameters
providerstringrequiredProvider slug, for example
openai,perplexity,deepgram,elevenlabs,twilio.
Request body
project_idstringRequired only for an org-wide key.
secretstringrequiredup to 8192 characterswrite-only, never returnedThe raw provider secret (API key, or a JSON blob for multi-field providers). Encrypted at rest; never returned.
Returns
200 OK
Response attributes
dataIntegrationStatusrequired4 attributes
providerstringrequiredproject_idstringconfiguredbooleanrequiredverifiedbooleanrequiredTrue when the provider accepted the key on save. False when it could not be checked (no check for this provider, a scoped key, or the provider was unreachable); the key is stored either way.
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 422 credential_rejected: the provider refused the key. Nothing is stored.
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X PUT "https://api.brightshoal.com/api/integrations/PROVIDER" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"secret": "whsec_..."
}'{
"data": {
"provider": "string",
"project_id": "proj_5f0c2a9e7b1d4c3e8a6f0b2d4c6e8a1f",
"configured": true,
"verified": true
}
}Remove a provider credential
DELETE/api/integrations/{provider}
Deletes the project's stored key for this provider.
Secret API key, not a viewer key. How it works
Path parameters
providerstringrequiredProvider slug, for example
openai,perplexity,deepgram,elevenlabs,twilio.
Query parameters
project_idstringThe project. Required with an org-wide key.
Returns
200 OK
Response attributes
dataIntegrationDeleteResultrequired2 attributes
providerstringrequireddeletedbooleanrequired
- 400 Validation error: usually
invalid_request, with the failing fields inissueswhen there are any - 401 Missing, malformed, unknown or revoked API key (
unauthorized) - 403 Refused, for example a viewer key on a write (
read_only_key), a role too low for the route (insufficient_role), or a route that needs a console session - 404 Not found, or outside what the key can see
- 429 Rate limit exceeded (
rate_limited). WaitRetry-Afterseconds. Budgets are per 60-second window: developer API 120 per key and 600 per organization; public chat 30 per IP address, except polling for updates (60 per conversation and IP address) and analytics events (120 per IP address).
curl -X DELETE "https://api.brightshoal.com/api/integrations/PROVIDER" \
-H "Authorization: Bearer $BRIGHTSHOAL_API_KEY"{
"data": {
"provider": "string",
"deleted": true
}
}