---
title: "Update Multiple Fields"
method: POST
path: "/fields/batch"
tags: ["Fields"]
---

# Update Multiple Fields

`POST /fields/batch`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/fields/batch`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

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.

**When nothing changes.** The endpoint compares every value against what the media already holds and writes only the differences. If no media matches your scope, or every entry you sent was dropped or already stored, the response is still `200` and its message reads `No field values changed`. Nothing else happens in that case: no `field_updated` automation runs, and no notification is raised. A request that does change something answers `Field Values are updated successfully` instead.

## Request body

- object
  - `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.

## Response `200`

Success

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)