---
title: "Batch classify and set attribute values"
method: POST
path: "/api/v3/files/{file_id}/facets/batch"
tags: ["Facets"]
---

# Batch classify and set attribute values

`POST /api/v3/files/{file_id}/facets/batch`

## Request

- Base URL: `https://api.lighton.ai`
- URL: `https://api.lighton.ai/api/v3/files/{file_id}/facets/batch`
- Auth: HTTP bearer

Execute multiple file facet actions in a single request.

All actions are **validated upfront** before any execution begins. If any
action has invalid fields, the entire batch is rejected with a 422 response
and no actions are executed.

On **domain errors** (e.g., unknown content type, sibling conflict), the
batch fails fast at the failing action. The error response includes an
`"index"` field (0-based) indicating which action caused the failure.
Actions before the failing index are committed; their results are not
returned. All verbs are idempotent — it is safe to re-send the entire
batch after fixing the error.

**Request:** `{"actions": [<action>, <action>, ...]}`

Each action object follows the same schema as the single-action
`POST /api/v3/files/{file_id}/facets` endpoint. Maximum 50 actions per batch.

**Response:** `{"results": [{"status": <code>, "data": <body|null>}, ...]}`

Results are in the same order as the input actions. The `data` key is
`null` for 204 actions (unclassify, clear_value).

See `POST /api/v3/files/{file_id}/facets` for available actions and their fields.

Requires edit access to the file.

## Path parameters

- `file_id` integer, required

## Request body

- FileFacetBatchRequest: Batch request for file facet operations. All actions are validated upfront before any execution begins.
  - `actions` FileFacetActionRequest[], required
    - `action` 'classify' | 'unclassify' | 'set_value' | 'clear_value', required
    - `content_type_path` string, required: Assigned content type path, e.g. legal:contract:nda.
    - `attribute_name` string, nullable: Attribute identifier in snake_case.
    - `value` unknown

## Response `200`

All actions executed successfully

- BatchResponse
  - `results` BatchResultItem[], required
    - `status` integer, required
    - `data` object, nullable

## Other responses

- `400`: Domain error with action index
- `401`: Authentication credentials were not provided or are invalid
- `403`: Insufficient permissions
- `404`: File not found
- `422`: Request body is valid JSON but one or more fields failed validation
- `503`: API is under maintenance. Check `GET /api/v3/system/status` for active periods and retry.

## Changes

- **2026-11-03** `63ecbc61b6a9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lighton/apis/lighton-api/changes/api/v3/files/:file_id/facets/batch/post.md)

---

[API](https://skmtc.dev/lighton/apis/lighton-api.md) - [All operations](https://skmtc.dev/lighton/apis/lighton-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lighton/apis/lighton-api/revisions/63ecbc61b6a9?raw)