Endpoint Examples

/classify

`POST` /sets/{set}/classify

Executes a predefined set workflow. For the current postings set, inputLocale defaults to en-US and outputs defaults to all outputs configured by the set.

company is required when requesting company or naicsStandard. title and description are required for all other outputs.

When outputs is omitted, all posting outputs are requested, so company, title, and description are required.

Path Parameters

Name	Type	Description
`set`	string	Predefined model set name.

Body Parameters

{
  "version": "2026.7",
  "input": {
    "inputLocale": "en-US",
    "title": "Software Engineer",
    "description": "Build and maintain backend APIs for customer-facing applications.",
    "outputs": [
      "lot"
    ]
  }
}

Code Examples

curl --request POST \
     --url https://api.lightcast.io/classification/sets/set/classify \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <Access_Token>' \
     --header 'content-type: application/json' \

Response Examples

//Example: LotOnly

{
  "data": {
    "result": {
      "lot": {
        "classifications": [
          {
            "id": "15-1252.00",
            "name": "Software Developers",
            "confidence": 0.97
          }
        ]
      }
    },
    "meta": {
      "setName": "postings",
      "setVersion": "2026.7"
    }
  },
  "errors": {}
}

//Example: CompanyAndNaics
{
  "data": {
    "result": {
      "company": {
        "id": 12345,
        "name": "Lightcast"
      },
      "naicsStandard": {
        "id": "541511"
      }
    },
    "meta": {
      "setName": "postings",
      "setVersion": "2026.7"
    }
  },
  "errors": {}
}

//Example: MalformedJson
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "malformed JSON"
}

//Example: MissingRequiredField
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "models is required"
}

//Example: MissingOutputInput
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "title and description are required for [lot] outputs"
}

//Example: InvalidReference
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "failed to resolve references"
}

//Example: EmptyModelGraph
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "models must contain at least one model request"
}

//Example: InvalidLocale
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "invalid locale: en-XX"
}

{
  "message": "Verification failed"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient scope"
}

//Example: ModelNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "model not found: unknown"
}

//Example: ModelVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "version not found: 0"
}

//Example: GraphModelNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "failed to resolve model 'jobTitle': model not found: unknown"
}

//Example: GraphModelVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "failed to resolve model 'jobTitle': version not found: 0"
}

//Example: SetNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "invalid set: unknown"
}

//Example: SetVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "invalid set: postings, version: 0"
}

//Example: NoRoute
{
  "title": "Not Found",
  "status": 404,
  "detail": "no matched route found"
}

{
  "title": "Method Not Allowed",
  "status": 405,
  "detail": "unsupported method"
}

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "classification failed while executing request"
}

`POST` /classify

Executes one or more named model requests. Each entry under models defines the external model name, model version, and input object.

String values beginning with $. may reference values in request body or output of requested model by $.context.<key> or $.models.<modelName>.output.<field>.

Body Parameters - Single Model

{
  "context": {
    "term": "Software Engineer",
    "description": "Build and maintain backend APIs for customer-facing applications."
  },
  "models": {
    "lot": {
      "model": "lot",
      "version": "7.20.0",
      "input": {
        "country": "US",
        "language": "en",
        "title": "$.context.term",
        "description": "$.context.description",
        "limit": 1,
        "threshold": 0
      }
    }
  }
}

Body Parameters - Multiple Models

{
  "context": {
    "terms": ["Software Engineer"],
    "descriptions": ["Build and maintain backend APIs for customer-facing applications."]
  },
  "models": {
    "lot": {
      "model": "lot",
      "version": "7.20.0",
      "input": {
        "country": "US",
        "language": "en",
        "title": "$.context.terms[0]",
        "description": "$.context.descriptions[0]",
        "limit": 1,
        "threshold": 0
      }
    },
    "lot-occ-semantic": {
        "model": "lot-occ-semantic",
        "version": "7.20.0",
        "input": {
            "terms": "$.context.terms",
            "descriptions": "$.context.descriptions",
            "limit": 1
        }
    }
  }
}

Body Parameters - Chaining Models

{
  "context": {
    "term": "inginero de software"
  },
  "models": {
    "translatedTitle": {
      "model": "translation",
      "version": "3.0.0",
      "input": {
        "locale": "es-ES",
        "term": "$.context.term"
      }
    },
    "titles": {
      "model": "titles",
      "version": "5.60.0",
      "input": {
        "title": "$.models.translatedTitle.output.translation"
      }
    }
  }
}

Code Examples

curl --request POST \
     --url https://api.lightcast.io/classification/classify \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <Access_Token>' \
     --header 'content-type: application/json' \

Response Examples

//Example: Lot

{
  "data": {
    "result": {
      "lot": {
        "classifications": {
          "lot": [
            {
              "id": "15-1252.00",
              "name": "Software Developers",
              "confidence": 0.97
            }
          ]
        }
      }
    }
  },
  "errors": {}
}

//Example: PartialFailure
{
  "data": {
    "result": {
      "lot": {
        "classifications": {
          "lot": [
            {
              "id": "15-1252.00",
              "name": "Software Developers",
              "confidence": 0.97
            }
          ]
        }
      }
    }
  },
  "errors": {
    "salary": [
      "failed to classify"
    ]
  }
}

//Example: MalformedJson
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "malformed JSON"
}

//Example: MissingRequiredField
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "models is required"
}

//Example: MissingOutputInput
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "title and description are required for [lot] outputs"
}

//Example: InvalidReference
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "failed to resolve references"
}

//Example: EmptyModelGraph
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "models must contain at least one model request"
}

//Example: InvalidLocale
{
  "title": "Invalid Request",
  "status": 400,
  "detail": "invalid locale: en-XX"
}

{
  "message": "Verification failed"
}

{
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient scope"
}

//Example: ModelNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "model not found: unknown"
}

//Example: ModelVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "version not found: 0"
}

//Example: GraphModelNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "failed to resolve model 'jobTitle': model not found: unknown"
}

//Example: GraphModelVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "failed to resolve model 'jobTitle': version not found: 0"
}

//Example: SetNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "invalid set: unknown"
}

//Example: SetVersionNotFound
{
  "title": "Not Found",
  "status": 404,
  "detail": "invalid set: postings, version: 0"
}

//Example: NoRoute
{
  "title": "Not Found",
  "status": 404,
  "detail": "no matched route found"
}

{
  "title": "Method Not Allowed",
  "status": 405,
  "detail": "unsupported method"
}

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "classification failed while executing request"
}