How It Works

Introduction

The Classification 2.0 API provides a flexible framework for chaining together classifier models in a single, declarative request.

Each request can define shared context, multiple model invocations, and references between model outputs — making it ideal for composable data-processing pipelines.

Classifiers and Extractors List

The Classification API contains a suit of APIs with different uses cases. Here is a high level description of each:

Service	Functionality
Skills Extract (multi)	Extracts recognized Lightcast skills from a block of text, supporting 17 Lightcast languages
Skills Classify	Provides semantic Lightcast skill matching for a raw skill term and its description.
Title Normalize	Normalizes a raw title to a matching Lightcast title.
Title Semantic	Provides semantic Lightcast title matching for a raw title and description.
Title Translate	Translates titles to English using Lightcast's proprietary multilingual machine translator (MMT). Currently supports German, Spanish, French, Portuguese, Italian, and Dutch.
LOT Classify - SpecOcc (multi)	Classifies a raw title and description to a matching Lightcast Specialized Occupation (GSF). Supports, German, Spanish, French, Portuguese, Italian, and Dutch
LOT Semantic	Provides semantic Lightcast occupation matching (Career Area, Occupation Group, Occupation, Specialized Occupation) for a raw title and description.
Company Normalize	Normalizes a raw company name to a matching Lightcast Company (ACME).
Postings Classify (multi)	All-in-one parser, extractor, normalizer, and classifier for raw job postings (company, title, description) to Lightcast taxonomies - includes Company, Title, LOT SpecOcc, SOC, ONET, CANOC, Skills, EmploymentType, Education, Salary, Years of Experience, Remote Type, Benefits, and more. Supports English, German, Spanish, French, Portuguese, Italian, and Dutch

Legend:

multi = multilingual

Chaining Overview

A classification request defines:

context — Shared input data accessible to all models.
models — A collection of model invocations that specify:
- The model name and version.
- The model’s input schema.
- Optional references to earlier model outputs or context values.

Structure

{
  "context": {
    "term": "inginero de software"
  },
  "models": {
    "translatedTitle": {
      "model": "translation",
      "version": "3.0.0",
      "input": {
        "locale": "es-ES",
        "term": "$.context.term"
      }
    },
    "lot": {
      "model": "lot",
      "version": "7.18.0",
      "input": {
        "country": "US",
        "language": "EN",
        "title": "$.models.translatedTitle.output.translation",
        "description": "Example job posting for a full-time developer."
      }
    }
  }
}

Referencing System

The Classification API supports a lightweight JSONPath-style referencing syntax for connecting model outputs and shared data.

Reference	Description
`$.context.<key>`	Accesses a value defined in the top-level `context` block.
`$.models.<modelName>.output.<field>`	Accesses an output property from a previously executed model.
`$.models.<modelName>.input.<field>`	(Optional) Accesses input data of another model for debugging or transparency.

Understanding Model Inputs and Outputs

Each model in the Classification API defines what data it accepts (inputs) and what data it produces (outputs). You can discover these structures dynamically by querying the /models/<model>/versions/<version> endpoint.

Example Request

GET /classification/models/lot/versions/7.18.0

Example Response (Simplified)

{
    "data": {
        "taxonomies": null,
        "releaseDate": "2026-04-14 22:51:26",
        "deprecationDate": "2026-04-14 22:51:26",
        "input": {
            "properties": {
                "country": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "language": {
                    "type": "string"
                },
                "limit": {
                    "type": "integer"
                },
                "threshold": {
                    "type": "number"
                },
                "title": {
                    "type": "string"
                },
                "translatedDescription": {
                    "type": "string"
                },
                "translatedTitle": {
                    "type": "string"
                }
            },
            "required": [
                "country",
                "language",
                "title",
                "description"
            ],
            "type": "object"
        },
        "output": {
            "$defs": {
                "classificationValue": {
                    "items": {
                        "additionalProperties": false,
                        "properties": {
                            "confidenceScore": {
                                "type": "number"
                            },
                            "id": {
                                "type": "string"
                            },
                            "ruleId": {
                                "type": "integer"
                            }
                        },
                        "required": [
                            "id",
                            "ruleId",
                            "confidenceScore"
                        ],
                        "type": "object"
                    },
                    "type": "array"
                }
            },
            "additionalProperties": false,
            "properties": {
                "classifications": {
                    "additionalProperties": false,
                    "properties": {
                        "canoc_lightcast": {
                            "$ref": "#/$defs/classificationValue"
                        },
                        "isco_standard": {
                            "$ref": "#/$defs/classificationValue"
                        },
                        "lot": {
                            "$ref": "#/$defs/classificationValue"
                        },
                        "onet_standard": {
                            "$ref": "#/$defs/classificationValue"
                        },
                        "soc_lightcast": {
                            "$ref": "#/$defs/classificationValue"
                        },
                        "soc_standard": {
                            "$ref": "#/$defs/classificationValue"
                        }
                    },
                    "required": [
                        "lot",
                        "onet_standard",
                        "soc_standard",
                        "soc_lightcast",
                        "canoc_lightcast",
                        "isco_standard"
                    ],
                    "type": "object"
                }
            },
            "required": [
                "classifications"
            ],
            "type": "object"
        }
    }
}

How to Use This Information

The input and output definitions describe what data the model expects and what it will return:

Inputs define the shape of the request data you must provide when invoking this model inside a /classify request. You can think of it as the model’s “API contract.”
Outputs define the structure of the data you can reference later in your workflow using the Referencing System.

For example, if the model above is named lot, you could access its output like so: "$.models.lot.output.occId"

Practical Example

If your workflow involves translating a title before classification:

{
  "context": { "term": "ingeniero de software" },
  "models": {
    "translatedTitle": {
      "model": "translation",
      "version": "3.0.0",
      "input": {
        "locale": "es-ES",
        "term": "$.context.term"
      }
    },
    "lot": {
      "model": "lot",
      "version": "7.18.0",
      "input": {
        "country": "US",
        "language": "EN",
        "title": "$.models.translatedTitle.output.translation",
        "description": "Full-time software engineer role..."
      }
    }
  }
}

Here:

The translation model’s output structure is found in its own ModelVersionMeta.
The lot model references that output (translation) as its title input.
You can discover both models’ input/output fields from their /models/<model>/versions/<version> metadata