Skip to content
SpeakDocs

Attach custom fields to your Speak AI media records

Create custom fields in Speak AI, list every field defined in your account, and update a single field or a whole batch of fields in one request.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

The Speak AI API exposes 4 fields 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.

Manage Fields.

What can you do with the fields endpoints?

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

Get All Fields

GET/fields

Retrieve Fields

This endpoint makes an HTTP GET request to retrieve a list of fields.

Request

The request does not require a request body. It simply makes a GET request to the endpoint https://api.speakai.co/v1/fields.

Response

The response will be a JSON object representing the list of fields. Below is a JSON schema representing the structure of the response:

{
 "type": "object",
 "properties": {
 "fields": {
 "type": "array",
 "items": {
 "type": "object",
 "properties": {
 "fieldId": {
 "type": "string"
 },
 "name": {
 "type": "string"
 },
 "type": {
 "type": "string"
 },
 "description": {
 "type": "string"
 }
 }
 }
 }
 }
}

The fields array contains objects with fieldId, name, type, and description properties, representing the details of each field.

Example request
curl -X GET 'https://api.speakai.co/v1/fields' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
Response

200 Success

The spec records this status code with no example body.

Create Field

POST/fields

Add Field

This endpoint allows you to add a new field.

Request Body

  • description (string, required): A description of the field.

  • name (string, required): The name of the field.

  • type (string, required): The type of the field.

  • privacyMode (string, required): The privacy mode of the field. “public” or “private”.

Response

The response will contain the details of the newly added field.

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 Name the field. This is the label you see in the app and the name you match on when you set values later. Required. Trimmed. No minimum or maximum length. The server trims the name and looks for an existing field with the same name in your company, so a duplicate returns 409, not 400.
description string Describe what the field is for. You can send an empty string. Optional. Empty string is accepted. the schema does not trim it, but the create helper trims it before saving and stores an empty string when you leave it out.
type string, required Set the data type the field stores. Required. Trimmed. The schema schema writes.allow(FieldType), which passes the enum object as an extra allowed value rather than constraining the string, so the validator accepts any non-empty string. An empty string is still rejected. A value outside the list fails when the field is saved, so a value outside the list fails when the field is saved. One of: text, url, boolean, date, datetime, number, currency.
isActive boolean Set whether the field is active. Leave it out and the field is created active. Optional. The declared default is true, but the middleware only reads the validation error and discards the converted value. The default that actually applies comes from the create helper, which defaults the parameter to true, matching the model default.
privacyMode string Choose whether values for this field are visible publicly or kept private. Optional. Trimmed. Same.allow(MediaPrivacyMode) pattern as type, so the validator accepts any non-empty string and the model enforces the list. Leave it out and the model default applies, which is public. One of: public, private.
prompt string Give the AI an instruction for filling this field automatically. Optional. Trimmed. Empty string is accepted.
allowedValues string[] List the values a user can pick for this field. Optional. Every item must be a string. No cap on the number of items. Leave it out and the field is created with an empty list.
allowedValuesMode string Choose whether a user can pick one value from allowedValues or several. Optional. This is the one property the schema really constrains, with.valid(.Object.values(AllowedValuesMode)), so anything outside the list returns 400. the schema also declares.default(‘multiple’), but the middleware discards converted values, so the default that applies comes from the create helper (multiple. One of: single, multiple.
otherValues boolean Allow a user to enter a value that is not in allowedValues. Optional. Leave it out and it is stored as false.
notApplicableValues string Set the text that marks this field as not applicable for a piece of media. Optional. Empty string is accepted. Leave it out and it is stored as an empty string.
Example request
curl -X POST 'https://api.speakai.co/v1/fields' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Currency",
  "name": "Currency",
  "type": "currency",
  "privacyMode": "public"
}'
Response

200 Success

The spec records this status code with no example body.

Update Field By Id

PUT/fields/{id}

Update Field Information

This endpoint allows you to update the information of a specific field.

Request Body

  • description (string, required): The updated description of the field.

  • name (string, required): The new name of the field.

Example:

{
 "description": "Currency Description Updated",
 "name": "New Updated Name",
 "privacyMode": "public"
}
Response

  • status (string): The status of the response.

  • data (object): An object containing the updated field information.

  • id (string): The ID of the field.

  • name (string): The name of the field.

  • description (string): The description of the field.

  • type (string): The type of the field.

  • isActive (boolean): Indicates if the field is active.

  • privacyMode (string): The privacy mode of the field.

  • createdAt (string): The date and time of creation.

  • updatedAt (string): The date and time of the last update.

Example Response:

{
 "status": "",
 "data": {
 "id": "",
 "name": "",
 "description": "",
 "type": "",
 "isActive": true,
 "privacyMode": "",
 "createdAt": "",
 "updatedAt": ""
 }
}

Parameters

Parameter In Type Required Description
id 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
name string, required Set the field name. You have to send this key on every update, even when the name is not changing. Required, and an empty string is accepted. Unlike the create schema this one does not trim. When the name differs from the stored one the server checks for another field with that name in your company and returns 409 if it finds one.
description string Set what the field is for. You can send an empty string. Optional. Empty string is accepted. Not trimmed.
privacyMode string Choose whether values for this field are visible publicly or kept private. Optional. Trimmed. The schema schema writes.allow(MediaPrivacyMode), which does not constrain the string, so the validator accepts any non-empty string. The stored record enforces the list. One of: public, private.
type string Change the data type the field stores. Optional. Trimmed. Same.allow(FieldType) pattern, so the validator accepts any non-empty string and the model enforces the list. One of: text, url, boolean, date, datetime, number, currency.
prompt string Give the AI an instruction for filling this field automatically. Optional. Trimmed. Empty string is accepted.
allowedValues string[] Replace the list of values a user can pick for this field. Optional. Every item must be a string. No cap on the number of items.
allowedValuesMode string Choose whether a user can pick one value from allowedValues or several. Optional. Enforced by the schema with.valid(.Object.values(AllowedValuesMode)), so anything outside the list returns 400. No default on the update schema. One of: single, multiple.
otherValues boolean Allow a user to enter a value that is not in allowedValues. Optional.
notApplicableValues string Set the text that marks this field as not applicable for a piece of media. Optional. Empty string is accepted.
Example request
curl -X PUT 'https://api.speakai.co/v1/fields/0172d3abbdd1' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Currency Description Updated",
  "name": "New Updated Name",
  "privacyMode": "public"
}'
Response

200 Success

The spec records this status code with no example body.

Update Multiple Fields

POST/fields/batch

Set custom field values across media. Scope with folderId (all media in a folder) and/or mediaIds (specific files). Each fields entry is { id, value }.

Request rules. Send either folderId, where an empty string counts, or a non-empty mediaIds array. Send neither and the request returns 400.

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
folderId string Set the values on every piece of media in this folder. Optional. Trimmed. Empty string is accepted, and the controller treats an empty string as a real target, matching media whose folderId is empty.
mediaIds string[] Set the values on these specific pieces of media. This takes precedence over folderId when you send both. Optional. Every item must be a string. No cap on the number of items. The controller checks mediaIds first, so folderId is ignored when the array is not empty.
fields object[], required List the field values you want to write. Required. Every item is an object with two keys: id (string, required, trimmed) is the field id, and value (required, any JSON type) is the value to store. The schema declares value as required with no type restriction, so a string, number, boolean, array or object is all accepted. No cap on the number of items. The controller drops any entry whose id or value is falsy, so sending an empty value, 0 or false does not clear a field.
Example request
curl -X POST 'https://api.speakai.co/v1/fields/batch' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "folderId": "your_folder_id_here",
  "mediaIds": [
    "your_media_id_here"
  ],
  "fields": [
    {
      "id": "your_field_id_here",
      "value": "The value you want to set"
    }
  ]
}'
Response

200 Success

The spec records this status code with no example body.

Get an API key on the Speak AI developer page.

Navigation
All sections

Type to search…

↑↓ navigate↵ selectEsc close