Skip to main content
POST
/
api
/
document-families
/
{id}
/
labels
Add a label to a document family
curl --request POST \
  --url https://platform.kodexa.ai/api/document-families/{id}/labels \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "tagId": "<string>",
  "path": "<string>"
}
'
{
  "activeAssistant": "aSDinaTvuI8gbWludGxpZnk=",
  "changeSequence": 123,
  "created": "2023-11-07T05:31:56Z",
  "createdOn": "2023-11-07T05:31:56Z",
  "deleteUserEmail": "<string>",
  "deleted": true,
  "deletedDate": "2023-11-07T05:31:56Z",
  "documentStatus": "<string>",
  "documentTaxonValidations": [
    {
      "taxonPath": "<string>",
      "taxonomyRef": "<string>",
      "validation": {
        "conditional": true,
        "conditionalFormula": "<string>",
        "description": "<string>",
        "detailFormula": "<string>",
        "disabled": true,
        "exceptionId": "<string>",
        "messageFormula": "<string>",
        "name": "<string>",
        "overridable": true,
        "ruleFormula": "<string>",
        "supportArticleId": "<string>"
      }
    }
  ],
  "executionTargets": {
    "instances": [
      {
        "actor": {
          "actorId": "<string>",
          "actorType": "<string>"
        },
        "contentObjectId": "<string>",
        "documentFamilyId": "<string>",
        "labelsToApply": [
          "<string>"
        ],
        "ref": "<string>",
        "taxonomyRefs": [
          "<string>"
        ],
        "type": "<string>"
      }
    ]
  },
  "id": "b1234567-89ab-cdef-0123-456789abcdef",
  "labelStatistics": {
    "averageLabelConfidence": {},
    "labelCounts": {},
    "maxLabelConfidence": {},
    "minLabelConfidence": {}
  },
  "locked": true,
  "metadata": {},
  "metadataSource": {},
  "modified": "2023-11-07T05:31:56Z",
  "numberOfContentExceptions": 123,
  "numberOfInsights": 123,
  "numberOfNotes": 123,
  "originalPath": "<string>",
  "path": "invoices/2025/q4/invoice-001.pdf",
  "pendingProcessing": true,
  "size": 245760,
  "storeRef": "<string>",
  "summary": "<string>",
  "updatedOn": "2023-11-07T05:31:56Z",
  "uuid": "<string>"
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Create one from the Kodexa platform UI under Settings > Access Tokens.

Path Parameters

​
id
string<uuid>
required

Unique identifier (UUID) of the resource.

Body

application/json

Request to add a label to a document family.

​
tagId
string
required

ID of the tag to apply as a label.

​
path
string

Optional path within the document to apply the label to.

Response

Updated document family

A document family groups related content objects representing a single logical document, tracking its processing lifecycle.

​
activeAssistant
string<byte>

The assistant currently processing this document.

​
changeSequence
integer<int32>

Optimistic locking version number.

​
created
string<date-time> | null

Original file creation date.

​
createdOn
string<date-time>

Timestamp when the document family was created.

​
deleteUserEmail
string | null

Email of the user who deleted the document family.

​
deleted
boolean

Whether the document family has been soft-deleted.

​
deletedDate
string<date-time> | null

Timestamp when the document family was soft-deleted.

​
documentStatus
string

Current processing status of the document.

​
documentTaxonValidations
object[]

Validation results against the document taxonomy.

​
executionTargets
object

Processing execution targets for this document.

​
id
string

Unique identifier (UUID) for the document family.

Example:

"b1234567-89ab-cdef-0123-456789abcdef"

​
labelStatistics
object

Statistics about labels applied to this document.

​
locked
boolean

Whether the document family is locked for processing.

​
metadata
object

Document metadata extracted during processing.

​
metadataSource
object

Maps metadata keys to their source content object IDs.

​
modified
string<date-time> | null

Original file modification date.

​
numberOfContentExceptions
integer<int32> | null

Count of content processing exceptions.

​
numberOfInsights
integer<int32> | null

Count of insights generated from this document.

​
numberOfNotes
integer<int64> | null

Count of notes attached to this document family.

​
originalPath
string | null

Original path before soft-deletion or rename.

​
path
string

File path or name of the document.

Example:

"invoices/2025/q4/invoice-001.pdf"

​
pendingProcessing
boolean

Whether the document family is queued for processing.

​
size
integer<int64>

File size in bytes.

Example:

245760

​
storeRef
string

Reference to the document store containing this document family.

​
summary
string

AI-generated summary of the document content.

​
updatedOn
string<date-time>

Timestamp when the document family was last updated.

​
uuid
string

Secondary UUID identifier.