Publish and embed a Speak AI voice agent

Enable or disable an agent's public share link, configure the embeddable widget's look and copy, and upload a company logo for it to display.

The Speak AI API exposes 4 sharing endpoints under the base URL https://api.speakai.co/v1. Every request needs the x-speakai-key and x-access-token headers described in Authentication.

Speak AI groups these 4 endpoints under the sharing resource. Each entry below links to the full reference for that endpoint further down this page.

POST/voice/sharing/{agentId}/share

Requires the OWNER or ADMIN role. Turns on the agent’s public share link and embeddable widget. Safe to call again to change isPublic/allowedDomains/expiresAt – the existing shareToken and shortCode are kept rather than rotated.

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	string	Yes

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field	Type	Description
`isPublic`	boolean	Defaults to false.
`allowedDomains`	string[]	Restrict the embeddable widget to these domains. Defaults to empty (no restriction).
`expiresAt`	string (date-time)

Example request

curl -X POST 'https://api.speakai.co/v1/voice/sharing/AGENT_ID/share' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

200 OK

Response body, application/json.

Field	Type	Description
`status`	string	One of: `success` .
`data`	object

data – 6 more fields

Field	Type	Description
`agentId`	string
`isPublic`	boolean
`shareToken`	string	Reused across repeated enable calls once generated. Part of the public share link and the widget embed.
`shortCode`	string	Short, URL-friendly alias for shareToken.
`allowedDomains`	string[]
`expiresAt`	string (date-time)

Example response, application/json.

{
  "status": "success",
  "data": {
    "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "isPublic": true,
    "shareToken": "9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e",
    "shortCode": "aB3dE7fG9h",
    "allowedDomains": [],
    "expiresAt": null
  }
}

403 Caller’s role is not OWNER or ADMIN

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

Example response, application/json.

{
  "status": "failed",
  "message": "You do not have permission to manage sharing"
}

404 Agent not found

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`requestId`	string
`code`	integer
`message`	string
`hints`	string[]

Example response, application/json.

{
  "status": "failed",
  "code": 404,
  "message": "Agent not found",
  "hints": []
}

DELETE/voice/sharing/{agentId}/share

Requires the OWNER or ADMIN role. Turns off public sharing and clears shareToken/shortCode – a later Enable Share issues new ones, so any previously distributed share link stops working permanently, not just while disabled.

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	string	Yes

Example request

curl -X DELETE 'https://api.speakai.co/v1/voice/sharing/AGENT_ID/share' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'

Response

200 OK

Response body, application/json.

Field	Type	Description
`status`	string	One of: `success` .
`message`	string

Example response, application/json.

{
  "status": "success",
  "message": "Share disabled successfully"
}

403 Caller’s role is not OWNER or ADMIN

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

Example response, application/json.

{
  "status": "failed",
  "message": "You do not have permission to manage sharing"
}

404 Agent not found

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`requestId`	string
`code`	integer
`message`	string
`hints`	string[]

Example response, application/json.

{
  "status": "failed",
  "code": 404,
  "message": "Agent not found",
  "hints": []
}

POST/voice/sharing/{agentId}/company-logo/sign

Sign Company Logo Upload

Requires the OWNER or ADMIN role. Issues a presigned S3 URL for uploading a widget company logo – you upload the file bytes directly to S3 with a PUT request, then persist the returned companyLogoUrl by calling Update Widget Config yourself. This endpoint does not update the agent.

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	string	Yes

Request body

Field	Type	Description
`contentType`	string, required	Required. One of: `image/png`, `image/jpeg`, `image/webp`, `image/svg+xml` .

Example request

curl -X POST 'https://api.speakai.co/v1/voice/sharing/AGENT_ID/company-logo/sign' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

200 OK

Response body, application/json.

Field	Type	Description
`status`	string	One of: `success` .
`data`	object
`data.uploadUrl`	string	Presigned S3 PUT URL, valid briefly. PUT the file’s bytes here directly with the same contentType.
`data.companyLogoUrl`	string	The public CDN URL the file will be reachable at once uploaded. Save this via Update Widget Config’s companyLogoUrl – uploading here does not update the agent by itself.
`data.key`	string	The S3 object key the file was signed for.

Example response, application/json.

{
  "status": "success",
  "data": {
    "uploadUrl": "https://s3.amazonaws.com/speak-uploads/voice-agents/a1b2c3d4/company-logo/1735689600000.png?X-Amz-Signature=...",
    "companyLogoUrl": "https://cdn.speakai.co/voice-agents/a1b2c3d4/company-logo/1735689600000.png",
    "key": "voice-agents/a1b2c3d4/company-logo/1735689600000.png"
  }
}

400 Validation failed

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

403 Caller’s role is not OWNER or ADMIN

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

Example response, application/json.

{
  "status": "failed",
  "message": "You do not have permission to manage sharing"
}

404 Agent not found

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`requestId`	string
`code`	integer
`message`	string
`hints`	string[]

Example response, application/json.

{
  "status": "failed",
  "code": 404,
  "message": "Agent not found",
  "hints": []
}

PATCH/voice/sharing/{agentId}/widget-config

Requires the OWNER or ADMIN role. Partial update of the embeddable widget’s appearance and copy – send at least one of the 24 keys listed here. Rejects any key outside this list (.unknown(false) in the server’s validation) rather than silently ignoring it, unlike most other partial-update endpoints in this API.

Parameters

Parameter	In	Type	Required	Description
`agentId`	path	string	Yes

Request body

Field	Type	Description
`displayMode`	string	One of: `floating`, `inline` .
`position`	string	One of: `bottom-left`, `bottom-right` .
`bubbleIconType`	string	One of: `avatar`, `generic` .
`buttonSize`	string	One of: `small`, `medium`, `large` .
`buttonColor`	string
`theme`	string	One of: `light`, `dark`, `auto` .
`compactMode`	boolean
`defaultMode`	string	One of: `voice`, `avatar` .
`showAvatar`	boolean
`fontFamily`	string
`borderRadius`	number
`backgroundColor`	string
`voiceEnabled`	boolean
`enableUserCamera`	boolean
`chatOpenByDefault`	boolean
`launcherTitle`	string
`launcherSubtitle`	string
`showLauncher`	boolean
`beforeCallTitle`	string
`beforeCallDescription`	string
`startButtonLabel`	string
`afterCallTitle`	string
`afterCallDescription`	string
`feedbackEnabled`	boolean
`companyLogoUrl`	string

Example request

curl -X PATCH 'https://api.speakai.co/v1/voice/sharing/AGENT_ID/widget-config' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'

Response

200 OK

Response body, application/json.

Field	Type	Description
`status`	string	One of: `success` .
`data`	object
`data.widgetConfig`	object

data.widgetConfig – 25 more fields

Field	Type	Description
`displayMode`	string	One of: `floating`, `inline` .
`position`	string	One of: `bottom-left`, `bottom-right` .
`bubbleIconType`	string	One of: `avatar`, `generic` .
`buttonSize`	string	One of: `small`, `medium`, `large` .
`buttonColor`	string
`theme`	string	One of: `light`, `dark`, `auto` .
`compactMode`	boolean
`defaultMode`	string	One of: `voice`, `avatar` .
`showAvatar`	boolean
`fontFamily`	string
`borderRadius`	number
`backgroundColor`	string
`voiceEnabled`	boolean
`enableUserCamera`	boolean
`chatOpenByDefault`	boolean
`launcherTitle`	string
`launcherSubtitle`	string
`showLauncher`	boolean
`beforeCallTitle`	string
`beforeCallDescription`	string
`startButtonLabel`	string
`afterCallTitle`	string
`afterCallDescription`	string
`feedbackEnabled`	boolean
`companyLogoUrl`	string

Example response, application/json.

{
  "status": "success",
  "data": {
    "widgetConfig": {
      "displayMode": "floating",
      "position": "bottom-right",
      "theme": "auto"
    }
  }
}

400 No widget configuration fields provided

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

403 Caller’s role is not OWNER or ADMIN

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`message`	string

Example response, application/json.

{
  "status": "failed",
  "message": "You do not have permission to manage sharing"
}

404 Agent not found

Response body, application/json.

Field	Type	Description
`status`	string	One of: `failed` .
`requestId`	string
`code`	integer
`message`	string
`hints`	string[]

Example response, application/json.

{
  "status": "failed",
  "code": 404,
  "message": "Agent not found",
  "hints": []
}

API reference for the base URL, authentication, and the error format.
Authenticate with the Speak AI API using access tokens
Upload audio and video to Speak AI and read insights
Create and update live transcription sessions
Analyze text notes with the Speak AI text endpoints

Get an API key on the Speak AI developer page.

Publish and embed a Speak AI voice agent

What can you do with the sharing endpoints?

Enable Share

Enable Share

Parameters

Request body

Disable Share

Disable Share

Parameters

Sign Company Logo Upload

Sign Company Logo Upload

Parameters

Request body

Update Widget Config

Update Widget Config

Parameters

Request body

Related pages