# Voice

## Endpoints

- `POST /platform/voice/audio`: [Create voice audio upload](https://docs.polymorfa.com/api/voice/create-voice-audio-upload)
- `POST /platform/voice/provider-credentials`: [Create voice provider credential](https://docs.polymorfa.com/api/voice/create-voice-provider-credential)
- `GET /platform/voice/audio`: [List voice audio](https://docs.polymorfa.com/api/voice/list-voice-audio)
- `GET /platform/voice/provider-credentials`: [List voice provider credentials](https://docs.polymorfa.com/api/voice/list-voice-provider-credentials)
- `GET /platform/voice/audio/{assetId}`: [Get voice audio](https://docs.polymorfa.com/api/voice/get-voice-audio)
- `GET /platform/voice/audio/{assetId}/preview`: [Get voice audio preview](https://docs.polymorfa.com/api/voice/get-voice-audio-preview)
- `GET /platform/voice/provider-credentials/{credentialId}`: [Get voice provider credential](https://docs.polymorfa.com/api/voice/get-voice-provider-credential)
- `PATCH /platform/voice/audio/{assetId}`: [Update voice audio](https://docs.polymorfa.com/api/voice/update-voice-audio)
- `POST /platform/voice/audio/tts`: [Synthesize voice audio](https://docs.polymorfa.com/api/voice/synthesize-voice-audio)
- `POST /platform/voice/audio/{assetId}/complete`: [Complete voice audio upload](https://docs.polymorfa.com/api/voice/complete-voice-audio-upload)
- `POST /platform/voice/provider-credentials/{credentialId}/verify`: [Verify voice provider credential](https://docs.polymorfa.com/api/voice/verify-voice-provider-credential)
- `DELETE /platform/voice/audio/{assetId}`: [Delete voice audio](https://docs.polymorfa.com/api/voice/delete-voice-audio)
- `DELETE /platform/voice/provider-credentials/{credentialId}`: [Delete voice provider credential](https://docs.polymorfa.com/api/voice/delete-voice-provider-credential)

## The audio asset object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `name` (string, required). Human-readable name for this resource.
- `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
- `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
- `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
- `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
- `originalContentType` (string, required, nullable). Category assigned to original content.
- `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
- `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
- `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
- `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
  - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
  - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
  - `model` (string, required). Specifies model for this management platform access voice audio tt.
  - `text` (string, required). The text that was spoken.
  - `characters` (integer, required). Characters sent to the provider.
  - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
  - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
- `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
- `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
- `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
- `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
- `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "name": "string",
  "source": "upload",
  "status": "pending_upload",
  "failureReason": "unsupported_format",
  "originalFormat": "mp3",
  "originalContentType": "string",
  "sizeBytes": 0,
  "durationMs": 0,
  "contentSha256": "string",
  "tts": {
    "provider": "elevenlabs",
    "voiceId": "string",
    "model": "string",
    "text": "string",
    "characters": 0,
    "keySource": "managed",
    "credentialId": "00000000-0000-4000-8000-000000000000"
  },
  "retentionDays": 0,
  "expiresAt": "2026-09-22T12:00:00Z",
  "inUseCount": 0,
  "revision": 0,
  "createdAt": "2026-09-22T12:00:00Z",
  "updatedAt": "2026-09-22T12:00:00Z",
  "readyAt": "2026-09-22T12:00:00Z"
}
```

## The voice provider key object

### Attributes

- `id` (string (uuid), required, format uuid). Identifier for this resource.
- `projectId` (string (uuid), required, nullable, format uuid). The project that may use the key, or null for every project of the team.
- `provider` (string, required). Specifies provider for this management platform access voice provider credential. Values: `elevenlabs`, `openai`.
- `label` (string, required). Specifies label for this management platform access voice provider credential.
- `keyFingerprint` (string, required). First 8 hex characters of the SHA-256 of the key. The key itself is never returned.
- `status` (string, required). Current status of this resource or operation. Values: `unverified`, `valid`, `invalid`.
- `verifiedAt` (string (date-time), required, nullable, format date-time). Timestamp for verified at.
- `lastError` (string, required, nullable). Specifies last error for this management platform access voice provider credential. Values: `unauthorized`, `quota_exceeded`, `forbidden_scope`, `provider_unavailable`.
- `revision` (integer, required). Specifies revision for this management platform access voice provider credential.
- `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
- `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
```json
{
  "id": "00000000-0000-4000-8000-000000000000",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "provider": "elevenlabs",
  "label": "string",
  "keyFingerprint": "string",
  "status": "unverified",
  "verifiedAt": "2026-09-22T12:00:00Z",
  "lastError": "unauthorized",
  "revision": 0,
  "createdAt": "2026-09-22T12:00:00Z",
  "updatedAt": "2026-09-22T12:00:00Z"
}
```

## Create voice audio upload

`POST https://api.polymorfa.com/platform/voice/audio` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Creates an audio asset and returns a URL to send the file to. Send the file with `POST` and the returned headers within 5 minutes, then call `POST /platform/voice/audio/{assetId}/complete`. MP3, WAV, OGG (Opus or Vorbis) and M4A (AAC), up to 16 MB and 10 minutes of audio.

### Body

- `projectId` (string (uuid), format uuid). Project that owns the asset. Required for team keys.
- `name` (string, required, length 1–100). Human-readable name for this resource.
- `contentType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). IANA media type that matches the payload. Values: `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/ogg`, `audio/mp4`, `audio/x-m4a`.
- `sizeBytes` (integer, required, range 1–16777216). File size in bytes, at most 16 MB.
- `retentionDays` (integer, range 1–3650). Delete the asset automatically this many days after creation (1 to 3650). Omit to keep it until you delete it.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/voice/audio" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "contentType": "audio/mpeg",
  "sizeBytes": 1
}'
```

### Responses

#### 201

Asset created in `pending_upload`, with the upload URL.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `asset` (object, required). Specifies asset for this management platform access create voice audio upload result.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
    - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
    - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
    - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
    - `originalContentType` (string, required, nullable). Category assigned to original content.
    - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
    - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
    - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
    - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
      - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
      - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
      - `model` (string, required). Specifies model for this management platform access voice audio tt.
      - `text` (string, required). The text that was spoken.
      - `characters` (integer, required). Characters sent to the provider.
      - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
      - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
    - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
    - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
    - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
    - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
    - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
    - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
    - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.
  - `upload` (object, required). Specifies upload for this management platform access create voice audio upload result.
    - `url` (string (uri), required, format uri). Send the file here with POST. The URL is the permission: send no Authorization header.
    - `method` (string, required). Specifies method for this management platform access voice audio upload. Values: `POST`.
    - `headers` (object, required). Headers to send with the file.
    - `maxBytes` (integer, required). Specifies max bytes for this management platform access voice audio upload.
    - `expiresAt` (string (date-time), required, format date-time). The upload URL stops working after this time (about 5 minutes).

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "asset": {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "source": "upload",
      "status": "pending_upload",
      "failureReason": "unsupported_format",
      "originalFormat": "mp3",
      "originalContentType": "string",
      "sizeBytes": 0,
      "durationMs": 0,
      "contentSha256": "string",
      "tts": {
        "provider": "elevenlabs",
        "voiceId": "string",
        "model": "string",
        "text": "string",
        "characters": 0,
        "keySource": "managed",
        "credentialId": "00000000-0000-4000-8000-000000000000"
      },
      "retentionDays": 0,
      "expiresAt": "2026-09-22T12:00:00Z",
      "inUseCount": 0,
      "revision": 0,
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z",
      "readyAt": "2026-09-22T12:00:00Z"
    },
    "upload": {
      "url": "https://example.com",
      "method": "POST",
      "headers": {},
      "maxBytes": 0,
      "expiresAt": "2026-09-22T12:00:00Z"
    }
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 402

`gate_limit_reached`: a Voice Automation limit is enforced and reached.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "billing_error",
    "code": "gate_limit_reached",
    "message": "A usage limit for this team or number was reached.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#gate-limit-reached"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`state_conflict`: the project already holds 500 audio assets.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: audio storage is not configured. `provider_unavailable`: the voice provider did not answer.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## Create voice provider credential

`POST https://api.polymorfa.com/platform/voice/provider-credentials` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Stores your ElevenLabs or OpenAI API key, encrypted, after checking it with the provider. A key the provider rejects is not stored. When the provider cannot be reached the key is stored with status `unverified`. The key is never returned.

### Body

- `provider` (string, required). Specifies provider for this management platform access create voice provider credential request. Values: `elevenlabs`, `openai`.
- `label` (string, required, length 1–100). Specifies label for this management platform access create voice provider credential request.
- `apiKey` (string, required, length 1–512). The provider API key. Write-only: it is never returned.
- `projectId` (string (uuid), nullable, format uuid). Limit the key to one project. Null or omitted makes it available to every project; project tokens must use their own project.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/voice/provider-credentials" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "elevenlabs",
  "label": "string",
  "apiKey": "string"
}'
```

### Responses

#### 201

Credential stored.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). The project that may use the key, or null for every project of the team.
  - `provider` (string, required). Specifies provider for this management platform access voice provider credential. Values: `elevenlabs`, `openai`.
  - `label` (string, required). Specifies label for this management platform access voice provider credential.
  - `keyFingerprint` (string, required). First 8 hex characters of the SHA-256 of the key. The key itself is never returned.
  - `status` (string, required). Current status of this resource or operation. Values: `unverified`, `valid`, `invalid`.
  - `verifiedAt` (string (date-time), required, nullable, format date-time). Timestamp for verified at.
  - `lastError` (string, required, nullable). Specifies last error for this management platform access voice provider credential. Values: `unauthorized`, `quota_exceeded`, `forbidden_scope`, `provider_unavailable`.
  - `revision` (integer, required). Specifies revision for this management platform access voice provider credential.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "provider": "elevenlabs",
    "label": "string",
    "keyFingerprint": "string",
    "status": "unverified",
    "verifiedAt": "2026-09-22T12:00:00Z",
    "lastError": "unauthorized",
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 402

`gate_limit_reached`: a Voice Automation limit is enforced and reached.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "billing_error",
    "code": "gate_limit_reached",
    "message": "A usage limit for this team or number was reached.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#gate-limit-reached"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`state_conflict`: the same key is already stored for this provider and project, or the team holds 50 credentials.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

`provider_credential_invalid`: the provider rejected the key.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "provider_credential_invalid",
    "message": "The voice provider rejected the key.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#provider-credential-invalid"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: credential storage is not configured.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## List voice audio

`GET https://api.polymorfa.com/platform/voice/audio` (Platform API)

Required permission: `voice:read`

**Required scope:** `voice:read`

Lists a project's audio assets, newest first.

### Query parameters

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `status` (string). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
- `cursor` (string, max length 200). Specifies cursor for this query parameter.
- `limit` (integer, range 1–100). Specifies limit for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/platform/voice/audio" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

A page of audio assets.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
  - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
  - `originalContentType` (string, required, nullable). Category assigned to original content.
  - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
  - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
  - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
  - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
    - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
    - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
    - `model` (string, required). Specifies model for this management platform access voice audio tt.
    - `text` (string, required). The text that was spoken.
    - `characters` (integer, required). Characters sent to the provider.
    - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
    - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
  - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
  - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
  - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
  - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.
- `page` (object, required). Specifies page for this management platform access list voice audio response.
  - `nextCursor` (string, required, nullable). Specifies next cursor for this management platform access voice audio page.
  - `hasMore` (boolean, required). Whether more.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "source": "upload",
      "status": "pending_upload",
      "failureReason": "unsupported_format",
      "originalFormat": "mp3",
      "originalContentType": "string",
      "sizeBytes": 0,
      "durationMs": 0,
      "contentSha256": "string",
      "tts": {
        "provider": "elevenlabs",
        "voiceId": "string",
        "model": "string",
        "text": "string",
        "characters": 0,
        "keySource": "managed",
        "credentialId": "00000000-0000-4000-8000-000000000000"
      },
      "retentionDays": 0,
      "expiresAt": "2026-09-22T12:00:00Z",
      "inUseCount": 0,
      "revision": 0,
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z",
      "readyAt": "2026-09-22T12:00:00Z"
    }
  ],
  "page": {
    "nextCursor": "string",
    "hasMore": true
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## List voice provider credentials

`GET https://api.polymorfa.com/platform/voice/provider-credentials` (Platform API)

Required permission: `voice:read`

**Required scope:** `voice:read`

Lists your stored ElevenLabs and OpenAI keys. Keys are never returned; `keyFingerprint` identifies them.

### Query parameters

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/voice/provider-credentials" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Provider credentials in creation order.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (array of object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). The project that may use the key, or null for every project of the team.
  - `provider` (string, required). Specifies provider for this management platform access voice provider credential. Values: `elevenlabs`, `openai`.
  - `label` (string, required). Specifies label for this management platform access voice provider credential.
  - `keyFingerprint` (string, required). First 8 hex characters of the SHA-256 of the key. The key itself is never returned.
  - `status` (string, required). Current status of this resource or operation. Values: `unverified`, `valid`, `invalid`.
  - `verifiedAt` (string (date-time), required, nullable, format date-time). Timestamp for verified at.
  - `lastError` (string, required, nullable). Specifies last error for this management platform access voice provider credential. Values: `unauthorized`, `quota_exceeded`, `forbidden_scope`, `provider_unavailable`.
  - `revision` (integer, required). Specifies revision for this management platform access voice provider credential.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "provider": "elevenlabs",
      "label": "string",
      "keyFingerprint": "string",
      "status": "unverified",
      "verifiedAt": "2026-09-22T12:00:00Z",
      "lastError": "unauthorized",
      "revision": 0,
      "createdAt": "2026-09-22T12:00:00Z",
      "updatedAt": "2026-09-22T12:00:00Z"
    }
  ]
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get voice audio

`GET https://api.polymorfa.com/platform/voice/audio/{assetId}` (Platform API)

Required permission: `voice:read`

**Required scope:** `voice:read`

### Path parameters

- `assetId` (string (uuid), required, format uuid). Identifier for the asset.

### Request

```bash
curl "https://api.polymorfa.com/platform/voice/audio/<assetId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The audio asset.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
  - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
  - `originalContentType` (string, required, nullable). Category assigned to original content.
  - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
  - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
  - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
  - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
    - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
    - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
    - `model` (string, required). Specifies model for this management platform access voice audio tt.
    - `text` (string, required). The text that was spoken.
    - `characters` (integer, required). Characters sent to the provider.
    - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
    - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
  - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
  - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
  - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
  - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "source": "upload",
    "status": "pending_upload",
    "failureReason": "unsupported_format",
    "originalFormat": "mp3",
    "originalContentType": "string",
    "sizeBytes": 0,
    "durationMs": 0,
    "contentSha256": "string",
    "tts": {
      "provider": "elevenlabs",
      "voiceId": "string",
      "model": "string",
      "text": "string",
      "characters": 0,
      "keySource": "managed",
      "credentialId": "00000000-0000-4000-8000-000000000000"
    },
    "retentionDays": 0,
    "expiresAt": "2026-09-22T12:00:00Z",
    "inUseCount": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z",
    "readyAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get voice audio preview

`GET https://api.polymorfa.com/platform/voice/audio/{assetId}/preview` (Platform API)

Required permission: `voice:read`

**Required scope:** `voice:read`

Returns a URL, valid for 5 minutes, to an Opus-in-Ogg preview of a `ready` asset for playback.

### Path parameters

- `assetId` (string (uuid), required, format uuid). Identifier for the asset.

### Request

```bash
curl "https://api.polymorfa.com/platform/voice/audio/<assetId>/preview" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Preview URL.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `url` (string (uri), required, format uri). Opus audio in an Ogg container, 16 kHz mono. Valid for about 5 minutes.
  - `contentType` (string, required, Media type: IANA `type/subtype` value matching the payload, such as `audio/ogg`, `audio/mpeg`, or `audio/aac`). IANA media type that matches the payload. Values: `audio/ogg`.
  - `expiresAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource expires.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "url": "https://example.com",
    "contentType": "audio/ogg",
    "expiresAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`asset_not_ready`: the asset is not `ready`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "asset_not_ready",
    "message": "The audio asset is not ready.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#asset-not-ready"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: audio storage is not configured. `provider_unavailable`: the voice provider did not answer.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## Get voice provider credential

`GET https://api.polymorfa.com/platform/voice/provider-credentials/{credentialId}` (Platform API)

Required permission: `voice:read`

**Required scope:** `voice:read`

### Path parameters

- `credentialId` (string (uuid), required, format uuid). Identifier for the credential.

### Request

```bash
curl "https://api.polymorfa.com/platform/voice/provider-credentials/<credentialId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The credential, without its key.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). The project that may use the key, or null for every project of the team.
  - `provider` (string, required). Specifies provider for this management platform access voice provider credential. Values: `elevenlabs`, `openai`.
  - `label` (string, required). Specifies label for this management platform access voice provider credential.
  - `keyFingerprint` (string, required). First 8 hex characters of the SHA-256 of the key. The key itself is never returned.
  - `status` (string, required). Current status of this resource or operation. Values: `unverified`, `valid`, `invalid`.
  - `verifiedAt` (string (date-time), required, nullable, format date-time). Timestamp for verified at.
  - `lastError` (string, required, nullable). Specifies last error for this management platform access voice provider credential. Values: `unauthorized`, `quota_exceeded`, `forbidden_scope`, `provider_unavailable`.
  - `revision` (integer, required). Specifies revision for this management platform access voice provider credential.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "provider": "elevenlabs",
    "label": "string",
    "keyFingerprint": "string",
    "status": "unverified",
    "verifiedAt": "2026-09-22T12:00:00Z",
    "lastError": "unauthorized",
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Update voice audio

`PATCH https://api.polymorfa.com/platform/voice/audio/{assetId}` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Renames an asset or changes its retention. Send `expectedRevision` to refuse the change with `409 voice_asset_revision_conflict` when the asset changed since you read it.

### Path parameters

- `assetId` (string (uuid), required, format uuid). Identifier for the asset.

### Body

- `expectedRevision` (integer, min 1). Apply the change only if the asset still has this `revision`.
- `name` (string, length 1–100). Human-readable name for this resource.
- `retentionDays` (integer, nullable, range 1–3650). Null removes automatic deletion. Retention counts from creation.

### Request

```bash
curl -X PATCH "https://api.polymorfa.com/platform/voice/audio/<assetId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "expectedRevision": 1,
  "name": "string",
  "retentionDays": 1
}'
```

### Responses

#### 200

The updated asset.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
  - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
  - `originalContentType` (string, required, nullable). Category assigned to original content.
  - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
  - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
  - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
  - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
    - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
    - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
    - `model` (string, required). Specifies model for this management platform access voice audio tt.
    - `text` (string, required). The text that was spoken.
    - `characters` (integer, required). Characters sent to the provider.
    - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
    - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
  - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
  - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
  - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
  - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "source": "upload",
    "status": "pending_upload",
    "failureReason": "unsupported_format",
    "originalFormat": "mp3",
    "originalContentType": "string",
    "sizeBytes": 0,
    "durationMs": 0,
    "contentSha256": "string",
    "tts": {
      "provider": "elevenlabs",
      "voiceId": "string",
      "model": "string",
      "text": "string",
      "characters": 0,
      "keySource": "managed",
      "credentialId": "00000000-0000-4000-8000-000000000000"
    },
    "retentionDays": 0,
    "expiresAt": "2026-09-22T12:00:00Z",
    "inUseCount": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z",
    "readyAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`voice_asset_revision_conflict`: the asset changed after `expectedRevision`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "voice_asset_revision_conflict",
    "message": "The audio asset changed since it was read.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-asset-revision-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Synthesize voice audio

`POST https://api.polymorfa.com/platform/voice/audio/tts` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Generates speech from text with ElevenLabs or OpenAI and stores it as an audio asset. Without `credentialId` Polymorfa's provider key is used; with it, your stored key for that provider. The provider processes the text. The asset converts asynchronously like an upload.

### Body

- `projectId` (string (uuid), format uuid). Project that owns the asset. Required for team keys.
- `name` (string, required, length 1–100). Human-readable name for this resource.
- `text` (string, required, length 1–5000). Text to speak: up to 5,000 characters for ElevenLabs and 4,096 for OpenAI.
- `provider` (string, required). Specifies provider for this management platform access synthesize voice audio request. Values: `elevenlabs`, `openai`.
- `voiceId` (string, required, length 1–64). ElevenLabs voice ID, or an OpenAI voice name such as `alloy`.
- `model` (string, length 1–64). ElevenLabs: `eleven_multilingual_v2` (default), `eleven_flash_v2_5`, `eleven_turbo_v2_5`. OpenAI: `gpt-4o-mini-tts` (default), `tts-1`, `tts-1-hd`.
- `credentialId` (string (uuid), format uuid). Use your stored key for the provider. Omit to use Polymorfa's key.
- `retentionDays` (integer, range 1–3650). Specifies retention days for this management platform access synthesize voice audio request.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/voice/audio/tts" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "text": "string",
  "provider": "elevenlabs",
  "voiceId": "string"
}'
```

### Responses

#### 201

Asset created, now `transcoding`.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
  - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
  - `originalContentType` (string, required, nullable). Category assigned to original content.
  - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
  - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
  - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
  - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
    - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
    - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
    - `model` (string, required). Specifies model for this management platform access voice audio tt.
    - `text` (string, required). The text that was spoken.
    - `characters` (integer, required). Characters sent to the provider.
    - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
    - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
  - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
  - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
  - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
  - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "source": "upload",
    "status": "pending_upload",
    "failureReason": "unsupported_format",
    "originalFormat": "mp3",
    "originalContentType": "string",
    "sizeBytes": 0,
    "durationMs": 0,
    "contentSha256": "string",
    "tts": {
      "provider": "elevenlabs",
      "voiceId": "string",
      "model": "string",
      "text": "string",
      "characters": 0,
      "keySource": "managed",
      "credentialId": "00000000-0000-4000-8000-000000000000"
    },
    "retentionDays": 0,
    "expiresAt": "2026-09-22T12:00:00Z",
    "inUseCount": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z",
    "readyAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 402

`gate_limit_reached`: a Voice Automation limit is enforced and reached.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "billing_error",
    "code": "gate_limit_reached",
    "message": "A usage limit for this team or number was reached.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#gate-limit-reached"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`state_conflict`: the project already holds 500 audio assets.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 422

`provider_credential_invalid`: the provider rejected your stored key.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "provider_credential_invalid",
    "message": "The voice provider rejected the key.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#provider-credential-invalid"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: audio storage is not configured. `provider_unavailable`: the voice provider did not answer.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 201.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## Complete voice audio upload

`POST https://api.polymorfa.com/platform/voice/audio/{assetId}/complete` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Confirms that the file was sent and starts conversion. The asset moves to `transcoding`, then to `ready` or `failed`; the `voice.asset_ready` or `voice.asset_failed` webhook reports the result.

### Path parameters

- `assetId` (string (uuid), required, format uuid). Identifier for the asset.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/voice/audio/<assetId>/complete" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The asset, now `transcoding`.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `source` (string, required). Specifies source for this management platform access voice audio asset. Values: `upload`, `tts`.
  - `status` (string, required). Current status of this resource or operation. Values: `pending_upload`, `uploaded`, `transcoding`, `ready`, `failed`.
  - `failureReason` (string, required, nullable). Specifies failure reason for this management platform access voice audio asset. Values: `unsupported_format`, `too_large`, `too_long`, `decode_failed`, `silent`, `tts_failed`, `processing_failed`.
  - `originalFormat` (string, required, nullable). Specifies original format for this management platform access voice audio asset. Values: `mp3`, `wav`, `ogg`, `m4a`.
  - `originalContentType` (string, required, nullable). Category assigned to original content.
  - `sizeBytes` (integer, required, nullable). Size of the original file in bytes.
  - `durationMs` (integer, required, nullable). Length of the converted audio, set when `ready`.
  - `contentSha256` (string, required, nullable). SHA-256 (hex) of the converted 16 kHz mono PCM audio, set when `ready`.
  - `tts` (object, required, nullable). Specifies tts for this management platform access voice audio asset.
    - `provider` (string, required). Specifies provider for this management platform access voice audio tt. Values: `elevenlabs`, `openai`.
    - `voiceId` (string, required). ElevenLabs voice ID or OpenAI voice name.
    - `model` (string, required). Specifies model for this management platform access voice audio tt.
    - `text` (string, required). The text that was spoken.
    - `characters` (integer, required). Characters sent to the provider.
    - `keySource` (string, required). Specifies key source for this management platform access voice audio tt. Values: `managed`, `customer`.
    - `credentialId` (string (uuid), required, nullable, format uuid). Your provider credential, when `keySource` is `customer`.
  - `retentionDays` (integer, required, nullable). Days after creation when the asset is deleted automatically. Null keeps it until you delete it.
  - `expiresAt` (string (date-time), required, nullable, format date-time). ISO 8601 timestamp when this resource expires.
  - `inUseCount` (integer, required). Campaigns and flows that use the asset. An asset in use cannot be deleted or expire.
  - `revision` (integer, required). Changes when you rename the asset or change its retention. Send it as `expectedRevision` to avoid overwriting another change.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.
  - `readyAt` (string (date-time), required, nullable, format date-time). Timestamp for ready at.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "name": "string",
    "source": "upload",
    "status": "pending_upload",
    "failureReason": "unsupported_format",
    "originalFormat": "mp3",
    "originalContentType": "string",
    "sizeBytes": 0,
    "durationMs": 0,
    "contentSha256": "string",
    "tts": {
      "provider": "elevenlabs",
      "voiceId": "string",
      "model": "string",
      "text": "string",
      "characters": 0,
      "keySource": "managed",
      "credentialId": "00000000-0000-4000-8000-000000000000"
    },
    "retentionDays": 0,
    "expiresAt": "2026-09-22T12:00:00Z",
    "inUseCount": 0,
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z",
    "readyAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`state_conflict`: the asset is not waiting for an upload, or the file was not received.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: audio storage is not configured. `provider_unavailable`: the voice provider did not answer.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## Verify voice provider credential

`POST https://api.polymorfa.com/platform/voice/provider-credentials/{credentialId}/verify` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Checks the stored key with the provider again and records the result in `status`, `verifiedAt` and `lastError`.

### Path parameters

- `credentialId` (string (uuid), required, format uuid). Identifier for the credential.

### Request

```bash
curl -X POST "https://api.polymorfa.com/platform/voice/provider-credentials/<credentialId>/verify" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

The credential with the new result.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, nullable, format uuid). The project that may use the key, or null for every project of the team.
  - `provider` (string, required). Specifies provider for this management platform access voice provider credential. Values: `elevenlabs`, `openai`.
  - `label` (string, required). Specifies label for this management platform access voice provider credential.
  - `keyFingerprint` (string, required). First 8 hex characters of the SHA-256 of the key. The key itself is never returned.
  - `status` (string, required). Current status of this resource or operation. Values: `unverified`, `valid`, `invalid`.
  - `verifiedAt` (string (date-time), required, nullable, format date-time). Timestamp for verified at.
  - `lastError` (string, required, nullable). Specifies last error for this management platform access voice provider credential. Values: `unauthorized`, `quota_exceeded`, `forbidden_scope`, `provider_unavailable`.
  - `revision` (integer, required). Specifies revision for this management platform access voice provider credential.
  - `createdAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was created.
  - `updatedAt` (string (date-time), required, format date-time). ISO 8601 timestamp when this resource was last updated.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "provider": "elevenlabs",
    "label": "string",
    "keyFingerprint": "string",
    "status": "unverified",
    "verifiedAt": "2026-09-22T12:00:00Z",
    "lastError": "unauthorized",
    "revision": 0,
    "createdAt": "2026-09-22T12:00:00Z",
    "updatedAt": "2026-09-22T12:00:00Z"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

`voice_not_enabled`: the team is not enrolled in the Voice Automation beta. Also `permission_denied` and `missing_scope`.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "voice_not_enabled",
    "message": "The Voice Automation beta is not enabled for this team.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-not-enabled"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

`voice_unavailable`: credential storage is not configured.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "voice_unavailable",
    "message": "Voice Automation storage is not available.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-unavailable"
}
```

## Delete voice audio

`DELETE https://api.polymorfa.com/platform/voice/audio/{assetId}` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Deletes the asset and its stored audio. Returns `409 voice_asset_in_use` while a campaign or flow uses it.

### Path parameters

- `assetId` (string (uuid), required, format uuid). Identifier for the asset.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/voice/audio/<assetId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Asset deleted.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "deleted": true
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

`voice_asset_in_use`: a campaign or flow uses the asset.
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "voice_asset_in_use",
    "message": "A campaign or flow uses this audio asset.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#voice-asset-in-use"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Delete voice provider credential

`DELETE https://api.polymorfa.com/platform/voice/provider-credentials/{credentialId}` (Platform API)

Required permission: `voice:manage`

**Required scope:** `voice:manage`

Deletes the stored key. Requests that name it with `credentialId` fail afterwards.

### Path parameters

- `credentialId` (string (uuid), required, format uuid). Identifier for the credential.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/platform/voice/provider-credentials/<credentialId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Credential deleted.
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `deleted` (boolean, required). Whether deleted. Values: `true`.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "deleted": true
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this management platform access public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```
