Set a field value

setFieldValue

PUT /api/v1/shares/{share_id}/field-values/{field_id}

Scope: fields.writeRate cost: 2

Set one custom field on one file, through the field’s own rules: the person must be allowed to set it, a field with allowed values takes one of them, and a value must suit the field’s type (422 otherwise)

A field whose change needs approval is held for its approver. Send If-Match with the ETag of the file’s field values as you last read them (GET …/field-values): without one the change is refused (428), and if anything changed since, 412. Answers every value on the file the person can see, as GET …/field-values does, with the new ETag.

Request

curl -X PUT "$FOLDR/api/v1/shares/$SHARE_ID/field-values/$FIELD_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{"path":"string","value":"string"}'

$FOLDR is your site’s address (for example https://files.example.com) and $TOKEN is an access token. See Getting access.

Parameters

Name	In	Type	Required	Description
share_id	path	string	Yes	The share’s id.
field_id	path	string (uuid)	Yes	The field’s id (see GET /fields).
If-Match	header	string	Yes	The ETag of the file’s field values as you last read them; ”*” for whatever they are now.

Request body

application/json, required: SetFieldValueBody

Field	Type	Description
path	string	Required. The path of the file (files only).
value	any	Required. The value: a string, a number, or true or false, as the field’s type takes (a date as 2027-01-31). A field with a list of allowed values takes one of them.

Example:

{
  "path": "string",
  "value": "string"
}

Responses

Status	Meaning	Body
200	The file’s field values now.	application/json: array of FieldValue

200 response

Header	Description
ETag	The entity tag of what was answered. Send it back as If-None-Match for a 304 while it is unchanged, or as If-Match to change it only while it is unchanged.

A JSON array of FieldValue.

Field	Type	Description
field_id	string (uuid)	Required. The field’s id (see GET /fields).
value	any	Required. The value: a string, number or boolean by the field’s type; a location is an object.
updated_at	string or null (date-time)	Required. When it was last set (RFC 3339, UTC).
updated_by	Person or null	Required. Who last set it, where known.

Example:

[
  {
    "field_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "value": "string",
    "updated_at": "2026-11-04T09:30:00Z",
    "updated_by": {
      "id": "string",
      "name": "string"
    }
  }
]

Errors

Every error is an application/problem+json document (ProblemDetails); branch on its type or code. See Errors.

Status	Problem types	When
400	invalid-path invalid-request	One of: Invalid path (invalid-path); Invalid request (invalid-request).
401	invalid-token	Invalid token (invalid-token).
403	insufficient-scope write-not-allowed	One of: Insufficient scope (insufficient-scope); Not allowed for this app (write-not-allowed).
404	not-found	Not found (not-found).
409	ambiguous-path not-a-file storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Not a file (not-a-file); Storage account not connected (storage-account-not-connected).
412	precondition-failed	Precondition failed (precondition-failed).
422	validation-failed	Validation failed (validation-failed).
423	checked-out	Checked out (checked-out).
428	precondition-required	Precondition required (precondition-required).
429	daily-write-limit rate-limited	One of: Daily write limit reached (daily-write-limit); Too many requests (rate-limited).
500	internal-error	Internal error (internal-error).
503	share-unavailable share-unreachable write-failed	One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).