Building a classification tree

This tutorial uses POST /api/v3/content-types and GET /api/v3/content-types. The full schema lives in the API reference.

After this tutorial you’ll have a content type tree with custom attributes, the schema that powers all facet queries. You define this once at the company level, then apply it to as many files as you need. There are two ways to build your schema:

Adopt starter templates: import ready-made trees for common verticals and customize them
Build from scratch: create your own trees, nodes, and attributes entirely

Option A: Adopt starter templates

LightOn ships with starter templates for legal, finance, healthcare, tech, and manufacturing. Browse what’s available, adopt the ones you need, then customize.

browse_templates.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

# Browse available starter templates (roots only)
response = requests.get(
    "https://api.lighton.ai/api/v3/content-types/templates",
    headers=headers,
    params={"depth": 0},
)

for tree in response.json().get("content_types", []):
    print(f"{tree['code']:20s} {tree['label']}")

This lists all available template roots. To adopt one or more:

adopt_templates.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

# Adopt the legal and finance starter trees
response = requests.post(
    "https://api.lighton.ai/api/v3/content-types",
    headers=headers,
    json={"action": "adopt", "content_types": ["legal", "finance"]},
)
print(response.json())

Once adopted, the trees become your company’s own content types, fully editable. You can rename nodes, add children, define new attributes, or delete what you don’t need using the same actions described below. Here’s what you get with legal and finance: Each node carries its own attributes and inherits from its parent. For example, legal defines confidentiality_level and jurisdiction. legal:contract adds parties, contract_value, and effective_date. legal:contract:nda adds counterparty, is_mutual, and duration_years, giving it 8 attributes total. Here’s a second schema with its attributes. A file can be classified under multiple trees at once: for example, an NDA could be both a legal:contract:nda and a finance:investment:due-diligence if it’s part of an investment deal.

Adoption behavior:

Trees are adopted wholesale: you cannot pick individual branches from a template.
Adoption is idempotent: re-adopting the same tree updates existing nodes based on their path. It does not auto-delete nodes you’ve removed or added since the last adoption.
After adoption, all content types are fully yours. The link to the original template is gone.

Option B: Build from scratch

Here’s what we’re going to build: All writes go to a single endpoint with an action field. Every action is idempotent and safe to replay. You can send a single action object or a JSON array to batch multiple actions in one call.

Step 1: Create your first Content Type

Start from zero and create a root content type called contract.

define_root_content_type.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

response = requests.post(
    "https://api.lighton.ai/api/v3/content-types",
    headers=headers,
    json={
        "action": "define_content_type",
        "code": "contract",
        "label": "Contract",
        "description": "Any legally binding agreement between two or more parties",
    },
)
print(response.json())

Returns 201 Created on first call, 200 OK if the node already exists (idempotent update). This makes scripts safe to run in CI pipelines or onboarding automations. path is the unique identifier you’ll use everywhere: to classify files, define attributes, and filter searches. For a root node, path equals code. inherit_attributes defaults to true, which means any attributes you define on contract are automatically available to all child types (contract:nda, contract:service-agreement, etc.). You define shared fields once on the parent.

Step 2: Build a tree of Content Types

Add child nodes. The path separator is :. LightOn builds the full path for you from parent_path + code.

define_child_content_types.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}
url = "https://api.lighton.ai/api/v3/content-types"

child_types = [
    {
        "action": "define_content_type",
        "parent_path": "contract",
        "code": "nda",
        "label": "Non-Disclosure Agreement",
        "description": "Confidentiality agreement preventing disclosure of proprietary information",
    },
    {
        "action": "define_content_type",
        "parent_path": "contract",
        "code": "service-agreement",
        "label": "Service Agreement",
        "description": "Agreement defining the delivery of services between a provider and a client",
    },
    {
        "action": "define_content_type",
        "parent_path": "contract:service-agreement",
        "code": "fixed-price",
        "label": "Fixed Price",
        "description": "Service agreement with a fixed total price, regardless of time spent",
    },
]

for payload in child_types:
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

Your tree is now:

contract
  contract:nda
  contract:service-agreement
    contract:service-agreement:fixed-price

You can go up to 4 levels deep. A company can have multiple independent trees (different roots). Each tree is completely isolated.

Read your classification tree at any time

from lighton import ContentType, LightOn

with LightOn() as client:
    # The subtree rooted at "contract", two levels deep
    for content_type in ContentType.list(client, path="contract", depth=2):
        print(content_type.path, content_type.label)
        for child in content_type.children:
            print(" ", child.path, child.label)

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

response = requests.get(
    "https://api.lighton.ai/api/v3/content-types",
    headers=headers,
    params={"path": "contract", "depth": 2, "include_attributes": False},
)
print(response.json())

Step 3: Define attributes

Attributes are the typed fields you want to store per document. Define them on a node, and if inherit_attributes: true, all children get them too. See Rules & constraints for naming restrictions, type immutability, and other validation rules.

Write descriptions for machines, not just humans. The description you give an attribute is what LightOn reads when it infers search filters from a natural-language query, so the wording changes which filter syntax it picks:

Person or entity names: include “name”, “author”, “examiner”, or “inventor” (e.g. "Full legal name of the other party in the agreement"). This signals a partial match is acceptable, so a query for “Acme” becomes counterparty:*Acme*.
Codes and identifiers: include “code”, “classification”, or “identifier” (e.g. "USPC classification code for the patent"). This signals exact match only, so the value is never guessed from surrounding topic words.

Shared attributes on `contract` (inherited by all subtypes)

define_shared_attributes.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}
url = "https://api.lighton.ai/api/v3/content-types"

attributes = [
    {
        "action": "define_attribute",
        "content_type_path": "contract",
        "name": "counterparty",
        "label": "Counterparty",
        "attribute_type": "text",
        "description": "Full legal name of the other party in the agreement",
        "required": True,
    },
    {
        "action": "define_attribute",
        "content_type_path": "contract",
        "name": "jurisdiction",
        "label": "Jurisdiction",
        "attribute_type": "multi-select",
        "description": "Countries whose law governs this agreement",
        "choices": ["FR", "US", "UK", "DE", "CH", "BE", "NL"],
    },
    {
        "action": "define_attribute",
        "content_type_path": "contract",
        "name": "effective_date",
        "label": "Effective Date",
        "attribute_type": "date",
        "description": "Date from which the contract is legally binding",
    },
    {
        "action": "define_attribute",
        "content_type_path": "contract",
        "name": "signed",
        "label": "Signed",
        "attribute_type": "boolean",
        "description": "Whether the contract has been signed by all parties",
    },
]

for payload in attributes:
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

Because contract has inherit_attributes: true, every child type (contract:nda, contract:service-agreement, etc.) automatically exposes these four attributes. You don’t need to redefine them.

NDA-specific attributes (only on `contract:nda`)

define_nda_attributes.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}
url = "https://api.lighton.ai/api/v3/content-types"

attributes = [
    {
        "action": "define_attribute",
        "content_type_path": "contract:nda",
        "name": "is_mutual",
        "label": "Mutual",
        "attribute_type": "boolean",
        "description": "True if confidentiality obligations apply to both parties",
    },
    {
        "action": "define_attribute",
        "content_type_path": "contract:nda",
        "name": "duration_years",
        "label": "Duration (years)",
        "attribute_type": "number",
        "description": "Number of years the confidentiality obligation lasts",
    },
]

for payload in attributes:
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

Service agreement-specific attributes

define_sa_attributes.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}
url = "https://api.lighton.ai/api/v3/content-types"

attributes = [
    {
        "action": "define_attribute",
        "content_type_path": "contract:service-agreement",
        "name": "contract_value",
        "label": "Contract Value (EUR)",
        "attribute_type": "number",
        "description": "Total value of the service agreement in euros",
    },
    {
        "action": "define_attribute",
        "content_type_path": "contract:service-agreement",
        "name": "payment_terms",
        "label": "Payment Terms",
        "attribute_type": "select",
        "description": "How payment is structured over the duration of the agreement",
        "choices": ["monthly", "quarterly", "milestone", "upfront", "upon-delivery"],
    },
]

for payload in attributes:
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())

How inheritance works

Attribute inheritance is resolved at query time: when you read a file’s facets, LightOn walks up the tree and collects attributes from each ancestor with inherit_attributes: true. Adding an attribute to a parent immediately makes it available on all descendants, no migration needed. For details on breaking the chain or shadowing inherited attributes, see Rules & constraints.

Full script: build the contract classification tree in one batch call

All schema operations can be batched in a single request by sending an {"actions": [...]} object to the /batch endpoint. LightOn processes them in order and fails fast on the first error. This is the recommended approach for onboarding automations.

batch_tree.py

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

response = requests.post(
    "https://api.lighton.ai/api/v3/content-types/batch",
    headers=headers,
    json={
        "actions": [
            {"action": "define_content_type", "code": "contract", "label": "Contract", "description": "Any legally binding agreement between two or more parties"},
            {"action": "define_content_type", "parent_path": "contract", "code": "nda", "label": "Non-Disclosure Agreement", "description": "Confidentiality agreement preventing disclosure of proprietary information"},
            {"action": "define_content_type", "parent_path": "contract", "code": "service-agreement", "label": "Service Agreement", "description": "Agreement defining the delivery of services between a provider and a client"},
            {"action": "define_content_type", "parent_path": "contract:service-agreement", "code": "fixed-price", "label": "Fixed Price", "description": "Service agreement with a fixed total price regardless of time spent"},
            {"action": "define_attribute", "content_type_path": "contract", "name": "counterparty", "label": "Counterparty", "attribute_type": "text", "description": "Full legal name of the other party in the agreement", "required": True},
            {"action": "define_attribute", "content_type_path": "contract", "name": "jurisdiction", "label": "Jurisdiction", "attribute_type": "multi-select", "description": "Countries whose law governs this agreement", "choices": ["FR", "US", "UK", "DE", "CH", "BE", "NL"]},
            {"action": "define_attribute", "content_type_path": "contract", "name": "effective_date", "label": "Effective Date", "attribute_type": "date", "description": "Date from which the contract is legally binding"},
            {"action": "define_attribute", "content_type_path": "contract", "name": "signed", "label": "Signed", "attribute_type": "boolean", "description": "Whether the contract has been signed by all parties"},
            {"action": "define_attribute", "content_type_path": "contract:nda", "name": "is_mutual", "label": "Mutual", "attribute_type": "boolean", "description": "True if confidentiality obligations apply to both parties"},
            {"action": "define_attribute", "content_type_path": "contract:nda", "name": "duration_years", "label": "Duration (years)", "attribute_type": "number", "description": "Number of years the confidentiality obligation lasts"},
            {"action": "define_attribute", "content_type_path": "contract:service-agreement", "name": "contract_value", "label": "Contract Value (EUR)", "attribute_type": "number", "description": "Total value of the service agreement in euros"},
            {"action": "define_attribute", "content_type_path": "contract:service-agreement", "name": "payment_terms", "label": "Payment Terms", "attribute_type": "select", "description": "How payment is structured over the duration of the agreement", "choices": ["monthly", "quarterly", "milestone", "upfront", "upon-delivery"]},
        ],
    },
)
print(response.json())

The response is a {"results": [...]} object with one entry per action, in order. Each entry has status (201 created, 200 updated) and a data object. If any action fails, the batch stops at that point. Actions before the failure are committed; actions after are not.

Verify: read your complete classification tree

from lighton import ContentType, LightOn

with LightOn() as client:
    # include_attributes populates each node's attribute definitions
    for content_type in ContentType.list(
        client, path="contract", include_attributes=True
    ):
        print(content_type.path, content_type.label)
        for attribute in content_type.attributes:
            print(" ", attribute.name, attribute.type, attribute.choices)

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['LIGHTON_API_KEY']}"}

response = requests.get(
    "https://api.lighton.ai/api/v3/content-types",
    headers=headers,
    params={"path": "contract", "include_attributes": True},
)
print(response.json())

The response shows own attributes per node. Inherited attributes are resolved when you read a file’s facets, not pre-expanded here.

Action reference

Action	What it does
`define_content_type`	Create or update a content type node (idempotent)
`undefine_content_type`	Delete a node, its subtree, and all file classifications + values under it
`define_attribute`	Create or update an attribute on a content type (idempotent)
`undefine_attribute`	Delete an attribute and all its stored values across all files

Overview

Build a searchable knowledge base

Classify and organise documents

Process documents on the fly

Option A: Adopt starter templates

Option B: Build from scratch

Step 1: Create your first Content Type

Step 2: Build a tree of Content Types

Read your classification tree at any time

Step 3: Define attributes

Shared attributes on `contract` (inherited by all subtypes)

NDA-specific attributes (only on `contract:nda`)

Service agreement-specific attributes

How inheritance works

Full script: build the contract classification tree in one batch call

Verify: read your complete classification tree

Action reference

​Option A: Adopt starter templates

​Option B: Build from scratch

​Step 1: Create your first Content Type

​Step 2: Build a tree of Content Types

​Read your classification tree at any time

​Step 3: Define attributes

​Shared attributes on contract (inherited by all subtypes)

​NDA-specific attributes (only on contract:nda)

​Service agreement-specific attributes

​How inheritance works

​Full script: build the contract classification tree in one batch call

​Verify: read your complete classification tree

​Action reference

Option A: Adopt starter templates

Option B: Build from scratch

Step 1: Create your first Content Type

Step 2: Build a tree of Content Types

Read your classification tree at any time

Step 3: Define attributes

Shared attributes on `contract` (inherited by all subtypes)

NDA-specific attributes (only on `contract:nda`)

Service agreement-specific attributes

How inheritance works

Full script: build the contract classification tree in one batch call

Verify: read your complete classification tree

Action reference