Skip to content
SpeakDocs

Configure questions a Speak AI voice agent asks

Attach question templates to an agent, reorder them, and map a question's answer onto a company Field. Manage the shared question-template library too.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

The Speak AI API exposes 8 questions 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.

What can you do with the questions endpoints?

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

Questions

Question Templates

Questions

List Questions

GET/voice/questions

List Questions

Lists the questions configured on one agent, in the order the agent asks them. Requires agentId – returns 404 if that agent does not exist or does not belong to your company.

These are agent-level instances of a template (see Question Templates below); each carries its own required/attempts/no-response settings and, optionally, a mappedFieldId that writes the caller’s answer onto a company Field after the call ends.

Parameters

Parameter In Type Required Description
agentId query string Yes Required. The agent whose questions to list.
enabledOnly query boolean No When true, only returns questions with enabled=true.
Example request
curl -X GET 'https://api.speakai.co/v1/voice/questions' \
  -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 .
data object
data.fields object[]
data.total integer
data.fields – 16 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use fieldId to identify it.
fieldId string Server-generated UUID. Immutable – sent in the body on create or update is silently dropped.
companyId string Stamped from the caller’s authenticated company. Sent in the body is silently dropped.
userId string Id of the user who created this question. Sent in the body is silently dropped.
agentId string Required on create. Immutable after create – sent on update is silently dropped.
templateId string Required on create. The question template this question is based on. Immutable after create – sent on update is silently dropped.
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean Defaults to false. Agent must collect this before ending the conversation.
maxPromptAttempts number Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as “number”.
noResponseBehavior string Defaults to move_to_next_question. One of: move_to_next_question, end_conversation .
triggerCondition string
order number Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
enabled boolean Defaults to true.
mappedFieldId string Id of a general company Field (see the Fields API) this question’s collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
createdAt string (date-time)
updatedAt string (date-time)
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "fields": [
      {
        "fieldId": "q-8f2a1c4e",
        "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "templateId": "tpl-email",
        "required": true,
        "maxPromptAttempts": 2,
        "noResponseBehavior": "move_to_next_question",
        "order": 0,
        "enabled": true,
        "mappedFieldId": "6650a1b2c3d4e5f678901234",
        "createdAt": "2026-08-01T12:00:00.000Z",
        "updatedAt": "2026-08-01T12:00:00.000Z"
      }
    ],
    "total": 1
  }
}

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": []
}

Create Question

POST/voice/questions

Create Question

Requires the OWNER or ADMIN role. Attaches a question template to an agent. agentId and templateId are both required; both must belong to your company (or, for templateId, be a public system template). Returns 404 if either is not found.

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
agentId string, required Required.
templateId string, required Required. Must reference a template your company can see (its own, or a system template).
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean
maxPromptAttempts number
noResponseBehavior string One of: move_to_next_question, end_conversation .
triggerCondition string
order number
enabled boolean
mappedFieldId string Id of an existing company Field to write this question’s collected answer onto after each call.
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]
Example request
curl -X POST 'https://api.speakai.co/v1/voice/questions' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response

201 Created

Response body, application/json.

Field Type Description
status string One of: success .
data object
data.field object
data.field – 16 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use fieldId to identify it.
fieldId string Server-generated UUID. Immutable – sent in the body on create or update is silently dropped.
companyId string Stamped from the caller’s authenticated company. Sent in the body is silently dropped.
userId string Id of the user who created this question. Sent in the body is silently dropped.
agentId string Required on create. Immutable after create – sent on update is silently dropped.
templateId string Required on create. The question template this question is based on. Immutable after create – sent on update is silently dropped.
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean Defaults to false. Agent must collect this before ending the conversation.
maxPromptAttempts number Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as “number”.
noResponseBehavior string Defaults to move_to_next_question. One of: move_to_next_question, end_conversation .
triggerCondition string
order number Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
enabled boolean Defaults to true.
mappedFieldId string Id of a general company Field (see the Fields API) this question’s collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
createdAt string (date-time)
updatedAt string (date-time)
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "field": {
      "fieldId": "q-8f2a1c4e",
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "templateId": "tpl-email",
      "required": true,
      "maxPromptAttempts": 2,
      "noResponseBehavior": "move_to_next_question",
      "order": 0,
      "enabled": true,
      "mappedFieldId": "6650a1b2c3d4e5f678901234",
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z"
    }
  }
}

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 questions"
}

404 Agent or template 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": []
}

Get Question

GET/voice/questions/{fieldId}

Get Question

Fetches a single question by id, scoped to your company.

Parameters

Parameter In Type Required Description
fieldId path string Yes
Example request
curl -X GET 'https://api.speakai.co/v1/voice/questions/FIELD_ID' \
  -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 .
data object
data.field object
data.field – 16 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use fieldId to identify it.
fieldId string Server-generated UUID. Immutable – sent in the body on create or update is silently dropped.
companyId string Stamped from the caller’s authenticated company. Sent in the body is silently dropped.
userId string Id of the user who created this question. Sent in the body is silently dropped.
agentId string Required on create. Immutable after create – sent on update is silently dropped.
templateId string Required on create. The question template this question is based on. Immutable after create – sent on update is silently dropped.
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean Defaults to false. Agent must collect this before ending the conversation.
maxPromptAttempts number Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as “number”.
noResponseBehavior string Defaults to move_to_next_question. One of: move_to_next_question, end_conversation .
triggerCondition string
order number Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
enabled boolean Defaults to true.
mappedFieldId string Id of a general company Field (see the Fields API) this question’s collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
createdAt string (date-time)
updatedAt string (date-time)
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "field": {
      "fieldId": "q-8f2a1c4e",
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "templateId": "tpl-email",
      "required": true,
      "maxPromptAttempts": 2,
      "noResponseBehavior": "move_to_next_question",
      "order": 0,
      "enabled": true,
      "mappedFieldId": "6650a1b2c3d4e5f678901234",
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z"
    }
  }
}

404 Field 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": "Field not found",
  "hints": []
}

Update Question

PUT/voice/questions/{fieldId}

Update Question

Requires the OWNER or ADMIN role. Partial update – only the keys you send are changed. agentId and templateId cannot be changed after create; sending them is silently dropped.

Parameters

Parameter In Type Required Description
fieldId 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
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean
maxPromptAttempts number
noResponseBehavior string One of: move_to_next_question, end_conversation .
triggerCondition string
order number
enabled boolean
mappedFieldId string Id of an existing company Field to write this question’s collected answer onto after each call.
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]
Example request
curl -X PUT 'https://api.speakai.co/v1/voice/questions/FIELD_ID' \
  -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.field object
data.field – 16 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use fieldId to identify it.
fieldId string Server-generated UUID. Immutable – sent in the body on create or update is silently dropped.
companyId string Stamped from the caller’s authenticated company. Sent in the body is silently dropped.
userId string Id of the user who created this question. Sent in the body is silently dropped.
agentId string Required on create. Immutable after create – sent on update is silently dropped.
templateId string Required on create. The question template this question is based on. Immutable after create – sent on update is silently dropped.
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean Defaults to false. Agent must collect this before ending the conversation.
maxPromptAttempts number Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as “number”.
noResponseBehavior string Defaults to move_to_next_question. One of: move_to_next_question, end_conversation .
triggerCondition string
order number Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
enabled boolean Defaults to true.
mappedFieldId string Id of a general company Field (see the Fields API) this question’s collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
createdAt string (date-time)
updatedAt string (date-time)
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "field": {
      "fieldId": "q-8f2a1c4e",
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "templateId": "tpl-email",
      "required": true,
      "maxPromptAttempts": 2,
      "noResponseBehavior": "move_to_next_question",
      "order": 0,
      "enabled": true,
      "mappedFieldId": "6650a1b2c3d4e5f678901234",
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z"
    }
  }
}

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 questions"
}

404 Field 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": "Field not found",
  "hints": []
}

Delete Question

DELETE/voice/questions/{fieldId}

Delete Question

Requires the OWNER or ADMIN role. Permanently removes the question from the agent and decrements the template’s usageCount.

Parameters

Parameter In Type Required Description
fieldId path string Yes
Example request
curl -X DELETE 'https://api.speakai.co/v1/voice/questions/FIELD_ID' \
  -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": "Field deleted 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 questions"
}

404 Field 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": "Field not found",
  "hints": []
}

Reorder Questions

PUT/voice/questions/reorder

Reorder Questions

Requires the OWNER or ADMIN role. Bulk-writes the order field on each listed question, then returns the agent’s full question list in its new order. Entries for a fieldId that does not belong to the given agentId are silently skipped (no error).

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
agentId string, required Required.
fieldOrders object[], required Required. The new order for some or all of the agent’s questions; each entry’s order value is written directly (not resequenced).
fieldOrders[].fieldId string, required
fieldOrders[].order number, required
Example request
curl -X PUT 'https://api.speakai.co/v1/voice/questions/reorder' \
  -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.fields object[]
data.fields – 16 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use fieldId to identify it.
fieldId string Server-generated UUID. Immutable – sent in the body on create or update is silently dropped.
companyId string Stamped from the caller’s authenticated company. Sent in the body is silently dropped.
userId string Id of the user who created this question. Sent in the body is silently dropped.
agentId string Required on create. Immutable after create – sent on update is silently dropped.
templateId string Required on create. The question template this question is based on. Immutable after create – sent on update is silently dropped.
customConfig object Agent-level override of the template’s defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
customConfig.displayLabel string
customConfig.question string The prompt text the agent speaks to ask this question. Renamed from promptText.
customConfig.confirmationText string
customConfig.validationPrompt string
customConfig.validation object
required boolean Defaults to false. Agent must collect this before ending the conversation.
maxPromptAttempts number Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as “number”.
noResponseBehavior string Defaults to move_to_next_question. One of: move_to_next_question, end_conversation .
triggerCondition string
order number Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
enabled boolean Defaults to true.
mappedFieldId string Id of a general company Field (see the Fields API) this question’s collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
createdAt string (date-time)
updatedAt string (date-time)
customConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "fields": [
      {
        "fieldId": "q-8f2a1c4e",
        "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "templateId": "tpl-email",
        "required": true,
        "maxPromptAttempts": 2,
        "noResponseBehavior": "move_to_next_question",
        "order": 0,
        "enabled": true,
        "mappedFieldId": "6650a1b2c3d4e5f678901234",
        "createdAt": "2026-08-01T12:00:00.000Z",
        "updatedAt": "2026-08-01T12:00:00.000Z"
      }
    ]
  }
}

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 questions"
}

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": []
}

Question Templates

List Question Templates

GET/voice/question-templates

List Question Templates

Lists the question templates visible to your company: Speak’s shared system templates, plus your own company’s templates.

Parameters

Parameter In Type Required Description
category query string No Filter to one category.
Example request
curl -X GET 'https://api.speakai.co/v1/voice/question-templates' \
  -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 .
data object
data.templates object[]
data.total integer
data.templates – 14 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use templateId to identify it.
templateId string Server-generated UUID. Immutable.
userId string Id of the user who created this template. Absent on a system template.
name string Required on create.
description string Required on create.
category string Required on create. One of: contact, booking, qualification, payment, custom .
fieldType string Required on create. One of: email, phone, date, time, datetime, text, number, boolean, choice, url .
defaultConfig object Required on create. displayLabel and question are both required within this object.
defaultConfig.displayLabel string
defaultConfig.question string The prompt text the agent speaks to ask this. Renamed from promptText.
defaultConfig.confirmationText string
defaultConfig.validationPrompt string
defaultConfig.validation object
isSystemTemplate boolean Always false for a template your company creates. Not settable directly.
isPublic boolean Defaults to false.
tags string[]
usageCount integer Incremented when a question is created from this template, decremented when that question is deleted. Not settable directly.
createdAt string (date-time)
updatedAt string (date-time)
defaultConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "templates": [
      {
        "templateId": "tpl-email",
        "name": "Email",
        "description": "The caller's email address",
        "category": "contact",
        "fieldType": "email",
        "defaultConfig": {
          "displayLabel": "Email",
          "question": "What is your email address?"
        },
        "isSystemTemplate": true,
        "isPublic": true,
        "tags": [],
        "usageCount": 12,
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Create Question Template

POST/voice/question-templates

Create Question Template

Requires the OWNER or ADMIN role. Creates a company-scoped template – the “custom question” a user names themselves rather than picking from Speak’s shared library. The server stamps companyId and forces isSystemTemplate to false, so this template is only ever visible to your company.

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
name string, required Required.
description string, required Required.
category string, required Required. One of: contact, booking, qualification, payment, custom .
fieldType string, required Required. One of: email, phone, date, time, datetime, text, number, boolean, choice, url .
defaultConfig object, required Required on create. displayLabel and question are both required within this object.
defaultConfig.displayLabel string
defaultConfig.question string The prompt text the agent speaks to ask this. Renamed from promptText.
defaultConfig.confirmationText string
defaultConfig.validationPrompt string
defaultConfig.validation object
isPublic boolean
tags string[]
defaultConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]
Example request
curl -X POST 'https://api.speakai.co/v1/voice/question-templates' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{}'
Response

201 Created

Response body, application/json.

Field Type Description
status string One of: success .
data object
data.template object
data.template – 14 more fields
Field Type Description
_id string MongoDB document id, included because every document has one; use templateId to identify it.
templateId string Server-generated UUID. Immutable.
userId string Id of the user who created this template. Absent on a system template.
name string Required on create.
description string Required on create.
category string Required on create. One of: contact, booking, qualification, payment, custom .
fieldType string Required on create. One of: email, phone, date, time, datetime, text, number, boolean, choice, url .
defaultConfig object Required on create. displayLabel and question are both required within this object.
defaultConfig.displayLabel string
defaultConfig.question string The prompt text the agent speaks to ask this. Renamed from promptText.
defaultConfig.confirmationText string
defaultConfig.validationPrompt string
defaultConfig.validation object
isSystemTemplate boolean Always false for a template your company creates. Not settable directly.
isPublic boolean Defaults to false.
tags string[]
usageCount integer Incremented when a question is created from this template, decremented when that question is deleted. Not settable directly.
createdAt string (date-time)
updatedAt string (date-time)
defaultConfig.validation – 6 more fields
Field Type
pattern string
minLength number
maxLength number
min number
max number
allowedValues string[]

Example response, application/json.

{
  "status": "success",
  "data": {
    "template": {
      "templateId": "tpl-email",
      "name": "Email",
      "description": "The caller's email address",
      "category": "contact",
      "fieldType": "email",
      "defaultConfig": {
        "displayLabel": "Email",
        "question": "What is your email address?"
      },
      "isSystemTemplate": true,
      "isPublic": true,
      "tags": [],
      "usageCount": 12,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  }
}

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 questions"
}

Get an API key on the Speak AI developer page.

Navigation
All sections

Type to search…

↑↓ navigate↵ selectEsc close