---
title: "Classify a file and set attributes"
method: POST
path: "/api/v3/files/{file_id}/facets"
tags: ["Facets"]
---

# Classify a file and set attributes

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

Apply content-type classifications to a file and set attribute values
(metadata) on it. This is how you tag a document with structured metadata
from your content-type schema.

**Typical workflow:**
1. **Classify** the file: `{"action": "classify",
   "content_type_path": "legal:contract:nda"}`
2. **Set attribute values**: `{"action": "set_value",
   "content_type_path": "legal:contract:nda",
   "attribute_name": "jurisdiction", "value": ["FR", "DE"]}`
3. **Read back** with `GET /api/v3/files/{file_id}/facets`

A file can be classified under **multiple content types**. Just call
`classify` for each one. Removing a classification (`unclassify`) cascades:
all attribute values under that content type are removed too.

**Actions:**
- `classify`: assign a content type to the file (idempotent)
- `unclassify`: remove a content type and all its attribute values
- `set_value`: set or update an attribute value (the content type must be classified first)
- `clear_value`: remove an attribute value

**Value types for `set_value`:**
- `text` / `rich-text` → string
- `number` → number or numeric string
- `date` → date string, normalized to `YYYY-MM-DD`
- `boolean` → `true` / `false`
- `select` → one string from `choices`
- `multi-select` → array of strings from `choices`

To clear a value, use `clear_value` (not `set_value` with `null`).

**Prerequisites:** Content types must be set up first. See
`GET /api/v3/content-types/templates` (browse templates) and
`POST /api/v3/content-types` (adopt or create).

Requires edit access to the file.

## Path parameters

- `file_id` integer, required

## Request body

- FileFacetActionRequest — Write operation for a file's facets (classifications + attribute values). Explicit verb-noun actions per FAC0012: - ``classify`` / ``unclassify``: T2 (file ↔ content type) - ``set_value`` / ``clear_value``: T3 (attribute value under an assigned content type) Value actions require ``attribute_name``; classification actions require only ``content_type_path``.
  - `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`

Content type already classified, or attribute value updated

- union
  - AttributeValueResponse
    - `name` string, required
    - `value` union, required — Attribute value. Shape depends on type: string, number, boolean, date string, or array of strings for multi-select.
      - string
      - integer
      - number
      - boolean
      - string[]
    - `content_type_path` string, required
  - ContentTypeAssignmentResponse
    - `content_type_path` string, required
    - `label` string, required

## Other responses

- `201` — Content type classified or attribute value created
- `204` — Content type unclassified or attribute value cleared
- `400` — Validation error or business rule violation
- `403` — No edit permission
- `404` — File or content type not found
- `422` — Request body is valid JSON but one or more fields failed validation

---

[API](https://skmtc.dev/lighton/apis/lighton-api.md) · [All operations](https://skmtc.dev/lighton/apis/lighton-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lighton/lighton-api/revisions/86c57e94ef15/schema)