---
title: "Attach custom fields to your Speak AI media records"
description: "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."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach custom fields to your Speak AI media records


import EndpointIndex from "@/components/api/EndpointIndex.astro";

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](/api/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.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/fields`](#get-fields) | Get All Fields |
| `POST` | [`/fields`](#post-fields) | Create Field |
| `PUT` | [`/fields/{id}`](#put-fields-id) | Update Field By Id |
| `POST` | [`/fields/batch`](#post-fields-batch) | Update Multiple Fields |

<h2 id="get-fields">Get All Fields</h2>

#### 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:

``` json
{
  "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.

<div slot="code">

<CodePanel label="Example request">

```bash
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'
```

</CodePanel>

<ResponsePanel id="get-fields" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="post-fields">Create Field</h2>

#### 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

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `description` | string |
| `name` | string |
| `type` | string |
| `privacyMode` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
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"
}'
```

</CodePanel>

<ResponsePanel id="post-fields" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="put-fields-id">Update Field By Id</h2>

#### 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:

``` json
{
"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:

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

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `description` | string |
| `name` | string |
| `privacyMode` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
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"
}'
```

</CodePanel>

<ResponsePanel id="put-fields-id" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

<h2 id="post-fields-batch">Update Multiple Fields</h2>

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 body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `folderId` | string |
| `mediaIds` | string[] |
| `fields` | object[] |
| `fields[].id` | string |
| `fields[].value` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
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"
}
  ]
}'
```

</CodePanel>

<ResponsePanel id="post-fields-batch" statuses={[{"code":"200","description":"Success"}]}>

<div slot="status-200">

**`200` Success**

The spec records this status code with no example body.

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-fields).

Source: https://docs.speakai.co/api/fields/index.mdx