{"openapi":"3.1.0","info":{"title":"Lightcast Classification API v2","version":"2.0.0","description":"## Introduction\nThe **Classification API** provides a flexible framework for chaining together classifier `models` in a single, declarative request.\n\nEach request can define shared context, multiple model invocations, and references between model outputs — making it ideal for composable data-processing pipelines.\n\n---\n\n## Overview\n\nA classification request defines:\n\n- `context` — Shared input data accessible to all models.\n- `models` — A collection of model invocations that specify:\n  - The model name and version.\n  - The model’s input schema.\n  - Optional references to earlier model outputs or context values.\n\n---\n\n## Structure\n\n```json\n{\n  \"context\": {\n    \"term\": \"inginero de software\"\n  },\n  \"models\": {\n    \"translatedTitle\": {\n      \"model\": \"translation\",\n      \"version\": \"2.0.0\",\n      \"input\": {\n        \"locale\": \"es-ES\",\n        \"term\": \"$.context.term\"\n      }\n    },\n    \"lot\": {\n      \"model\": \"lot\",\n      \"version\": \"7.9.0\",\n      \"input\": {\n        \"country\": \"US\",\n        \"language\": \"EN\",\n        \"title\": \"$.models.translatedTitle.output.translation\",\n        \"description\": \"Example job posting for a full-time developer.\"\n      }\n    }\n  }\n}\n```\n---\n## 🔗 Referencing System\nThe Classification API supports a lightweight JSONPath-style referencing syntax for connecting model outputs and shared data. \n\n| Reference                             | Description                                                                      |\n| ------------------------------------- | -------------------------------------------------------------------------------- |\n| `$.context.<key>`                     | Accesses a value defined in the top-level `context` block.                       |\n| `$.models.<modelName>.output.<field>` | Accesses an output property from a previously executed model.                    |\n| `$.models.<modelName>.input.<field>`  | *(Optional)* Accesses input data of another model for debugging or transparency. |\n\n## 🧩 Understanding Model Inputs and Outputs\n\nEach model in the Classification API defines **what data it accepts (inputs)** and **what data it produces (outputs).**\nYou can discover these structures dynamically by querying the `/models/<model>/versions/<version>` endpoint.\n\n### 🔍 Example Request\n\n```\nGET /classification/models/lot/versions/7.9.0\n```\n\n### 📦 Example Response (Simplified)\n```json\n{\n  \"data\": {\n    \"releaseDate\": \"2023-07-14T16:08:51Z\",\n    \"deprecationDate\": \"2023-09-12T16:08:51Z\",\n    \"input\": {\n      \"type\": \"object\",\n      \"required\": [\"country\", \"language\", \"title\", \"description\"],\n      \"properties\": {\n        \"country\": { \"type\": \"string\" },\n        \"language\": { \"type\": \"string\" },\n        \"title\": { \"type\": \"string\" },\n        \"description\": { \"type\": \"string\" }\n      }\n    },\n    \"output\": {\n      \"type\": \"object\",\n      \"required\": [\"occId\", \"specOccId\", \"careerAreaId\"],\n      \"properties\": {\n        \"occId\": { \"type\": \"integer\" },\n        \"specOccId\": { \"type\": \"integer\" },\n        \"careerAreaId\": { \"type\": \"integer\" }\n      }\n    }\n  }\n}\n```\n### 🧠 How to Use This Information\nThe `input` and `output` definitions describe what data the model expects and what it will return:\n- **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.”\n- **Outputs** define the structure of the data you can reference later in your workflow using the Referencing System.\n\nFor example, if the model above is named lot, you could access its output like so:\n`\"$.models.lot.output.occId\"`\n\n### 🔁 Practical Example\nIf your workflow involves translating a title before classification:\n```json\n{\n  \"context\": { \"term\": \"ingeniero de software\" },\n  \"models\": {\n    \"translatedTitle\": {\n      \"model\": \"translation\",\n      \"version\": \"2.0.0\",\n      \"input\": {\n        \"locale\": \"es-ES\",\n        \"term\": \"$.context.term\"\n      }\n    },\n    \"lot\": {\n      \"model\": \"lot\",\n      \"version\": \"7.9.0\",\n      \"input\": {\n        \"country\": \"US\",\n        \"language\": \"EN\",\n        \"title\": \"$.models.translatedTitle.output.translation\",\n        \"description\": \"Full-time software engineer role...\"\n      }\n    }\n  }\n}\n```\nHere:\n- The translation model’s output structure is found in its own ModelVersionMeta.\n- The lot model references that output (translation) as its title input.\n- You can discover both models’ input/output fields from their `/models/<model>/versions/<version>` metadata."},"security":[{"oauth2":["classmaster"]}],"servers":[{"url":"https://api.lightcast.io/classification"}],"tags":[{"name":"Status","description":"Service health."},{"name":"Meta","description":"Service metadata."},{"name":"Models","description":"Model discovery and model version metadata."},{"name":"Sets","description":"Predefined classification model sets."},{"name":"Classification","description":"Classification execution."}],"paths":{"/status":{"get":{"tags":["Status"],"summary":"Health check","description":"Returns service health. Check `data.healthy`; do not rely on HTTP status alone.","operationId":"getStatus","responses":{"200":{"description":"Service health.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/meta":{"get":{"tags":["Meta"],"summary":"Get service metadata","operationId":"getMeta","responses":{"200":{"description":"Service metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/models":{"get":{"tags":["Models"],"summary":"List available models","description":"Returns available classifier models and their registered versions.","operationId":"listModels","responses":{"200":{"description":"Available models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelsResponse"}}},"links":{"GetModel":{"operationId":"getModel","parameters":{"path.model":"$response.body#/data/0/modelName"}},"ListModelVersions":{"operationId":"listModelVersions","parameters":{"path.model":"$response.body#/data/0/modelName"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/models/{model}":{"parameters":[{"$ref":"#/components/parameters/Model"}],"get":{"tags":["Models"],"summary":"Get model metadata","operationId":"getModel","responses":{"200":{"description":"Model metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelMetaResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/models/{model}/versions":{"parameters":[{"$ref":"#/components/parameters/Model"}],"get":{"tags":["Models"],"summary":"List model versions","operationId":"listModelVersions","responses":{"200":{"description":"Model versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelVersionsResponse"}}},"links":{"GetModelVersion":{"operationId":"getModelVersion","parameters":{"path.model":"$request.path.model","path.version":"$response.body#/data/0/version"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/models/{model}/versions/{version}":{"parameters":[{"$ref":"#/components/parameters/Model"},{"$ref":"#/components/parameters/Version"}],"get":{"tags":["Models"],"summary":"Get model version metadata","description":"Returns a model version's taxonomies and raw JSON Schema objects for model input and output.","operationId":"getModelVersion","responses":{"200":{"description":"Model version metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelVersionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sets":{"get":{"tags":["Sets"],"summary":"List predefined sets","operationId":"listSets","responses":{"200":{"description":"Available predefined model sets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetsResponse"}}},"links":{"GetSet":{"operationId":"getSet","parameters":{"path.set":"$response.body#/data/0/name"}},"ListSetVersions":{"operationId":"listSetVersions","parameters":{"path.set":"$response.body#/data/0/name"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sets/{set}":{"parameters":[{"$ref":"#/components/parameters/Set"}],"get":{"tags":["Sets"],"summary":"Get latest set metadata","operationId":"getSet","responses":{"200":{"description":"Latest set metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatestSetResponse"}}},"links":{"GetSetVersion":{"operationId":"getSetVersion","parameters":{"path.set":"$request.path.set","path.setVersion":"$response.body#/data/latestVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sets/{set}/versions":{"parameters":[{"$ref":"#/components/parameters/Set"}],"get":{"tags":["Sets"],"summary":"List set versions","operationId":"listSetVersions","responses":{"200":{"description":"Set versions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVersionsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sets/{set}/versions/{setVersion}":{"parameters":[{"$ref":"#/components/parameters/Set"},{"$ref":"#/components/parameters/SetVersion"}],"get":{"tags":["Sets"],"summary":"Get set version metadata","operationId":"getSetVersion","responses":{"200":{"description":"Set version metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetVersionResponse"}}},"links":{"ClassifySet":{"operationId":"classifySet","parameters":{"path.set":"$request.path.set"},"requestBody":{"version":"$request.path.setVersion","input":{"inputLocale":"$response.body#/data/locales/0","title":"Software Engineer","description":"Builds and maintains production software services.","outputs":"$response.body#/data/output"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/sets/{set}/classify":{"parameters":[{"$ref":"#/components/parameters/Set"}],"post":{"tags":["Classification"],"summary":"Classify with a predefined set","description":"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.\n\n`company` is required when requesting `company` or `naicsStandard`. `title` and `description` are required for all other outputs. \n\nWhen `outputs` is omitted, all posting outputs are requested, so `company`, `title`, and `description` are required.","operationId":"classifySet","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetClassifyRequest"},"examples":{"lotOnly":{"summary":"Request LOT Output only","value":{"version":"2026.7","input":{"inputLocale":"en-US","title":"Software Engineer","description":"Build and maintain backend APIs for customer-facing applications.","outputs":["lot"]}}},"defaultPostingOutputs":{"summary":"Request default posting outputs","value":{"input":{"inputLocale":"en-US","company":"Lightcast","title":"Software Engineer","description":"Build and maintain backend APIs for customer-facing applications."}}}}}}},"responses":{"200":{"description":"Set classification result. Recoverable per-output failures are returned under `errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetClassifyResponse"},"examples":{"lotOnly":{"value":{"data":{"result":{"lot":{"classifications":[{"id":"15-1252.00","name":"Software Developers","confidence":0.97}]}},"meta":{"setName":"postings","setVersion":"2026.7"}},"errors":{}}},"companyAndNaics":{"value":{"data":{"result":{"company":{"id":12345,"name":"Lightcast"},"naicsStandard":{"id":"541511"}},"meta":{"setName":"postings","setVersion":"2026.7"}},"errors":{}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/classify":{"post":{"tags":["Classification"],"summary":"Compose classification models","description":"Executes one or more named model requests. Each entry under `models` defines the external model name, model version, and input object.\n\nString values beginning with `$.` may reference values in request body or output of requested model by `$.context.<key>` or `$.models.<modelName>.output.<field>`.","operationId":"classifyGraph","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyRequest"},"examples":{"lot":{"value":{"models":{"lot":{"model":"lot","version":"7.17.0","input":{"country":"US","language":"en","title":"Software Engineer","translatedTitle":"Software Engineer","description":"Build and maintain backend APIs for customer-facing applications.","limit":1,"threshold":0}}}}}}}}},"responses":{"200":{"description":"Classification graph result. Recoverable per-model failures are returned under `errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifyResponse"},"examples":{"lot":{"value":{"data":{"result":{"lot":{"classifications":{"lot":[{"id":"15-1252.00","name":"Software Developers","confidence":0.97}]}}}},"errors":{}}},"partialFailure":{"value":{"data":{"result":{"lot":{"classifications":{"lot":[{"id":"15-1252.00","name":"Software Developers","confidence":0.97}]}}}},"errors":{"salary":["failed to classify"]}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client credentials. The deployed API gateway enforces bearer-token authentication; the local Gin service does not perform authorization itself.","flows":{"clientCredentials":{"tokenUrl":"https://auth.emsicloud.com/connect/token","scopes":{"classmaster":"Access to the Lightcast Classification API."}}}}},"parameters":{"Model":{"name":"model","in":"path","required":true,"description":"External classifier model name, available models are listed in the Models endpoint.","schema":{"type":"string"}},"Version":{"name":"version","in":"path","required":true,"description":"Model version.","schema":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+$"}},"Set":{"name":"set","in":"path","required":true,"description":"Predefined model set name.","schema":{"type":"string"}},"SetVersion":{"name":"setVersion","in":"path","required":true,"description":"Predefined model set version.","schema":{"type":"string","pattern":"^[0-9]{4}\\.(?:0?[1-9]|1[0-3])$"}}},"responses":{"BadRequest":{"description":"Request syntax or body validation failed. Use for malformed JSON, missing required body fields, invalid request-local references, empty model graphs, invalid locales, or input that does not match the required shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"malformedJson":{"value":{"title":"Invalid Request","status":400,"detail":"malformed JSON"}},"missingRequiredField":{"value":{"title":"Invalid Request","status":400,"detail":"models is required"}},"missingOutputInput":{"value":{"title":"Invalid Request","status":400,"detail":"title and description are required for [lot] outputs"}},"invalidReference":{"value":{"title":"Invalid Request","status":400,"detail":"failed to resolve references"}},"emptyModelGraph":{"value":{"title":"Invalid Request","status":400,"detail":"models must contain at least one model request"}},"invalidLocale":{"value":{"title":"Invalid Request","status":400,"detail":"invalid locale: en-XX"}}}}}},"Unauthorized":{"description":"Missing, invalid, or expired bearer token. Returned by the API gateway before the request reaches this service.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayErrorResponse"},"examples":{"unauthorized":{"value":{"message":"Verification failed"}}}}}},"Forbidden":{"description":"Authenticated client does not have permission to access this API or lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"forbidden":{"value":{"title":"Forbidden","status":403,"detail":"insufficient scope"}}}}}},"NotFound":{"description":"Requested resource does not exist. Use for missing model, model version, set, set version, or other named resource identifiers; unmatched routes may also return this shape.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"modelNotFound":{"value":{"title":"Not Found","status":404,"detail":"model not found: unknown"}},"modelVersionNotFound":{"value":{"title":"Not Found","status":404,"detail":"version not found: 0"}},"graphModelNotFound":{"value":{"title":"Not Found","status":404,"detail":"failed to resolve model 'jobTitle': model not found: unknown"}},"graphModelVersionNotFound":{"value":{"title":"Not Found","status":404,"detail":"failed to resolve model 'jobTitle': version not found: 0"}},"setNotFound":{"value":{"title":"Not Found","status":404,"detail":"invalid set: unknown"}},"setVersionNotFound":{"value":{"title":"Not Found","status":404,"detail":"invalid set: postings, version: 0"}},"noRoute":{"value":{"title":"Not Found","status":404,"detail":"no matched route found"}}}}}},"MethodNotAllowed":{"description":"HTTP method is not supported for the route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"methodNotAllowed":{"value":{"title":"Method Not Allowed","status":405,"detail":"unsupported method"}}}}}},"InternalServerError":{"description":"Unexpected server error after the request has been accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"internal":{"value":{"title":"Internal Server Error","status":500,"detail":"classification failed while executing request"}},"unhandled":{"value":{"title":"Internal Server Error","status":500,"detail":null}}}}}}},"schemas":{"StatusResponse":{"type":"object","description":"Health status of the Classification API service.","properties":{"data":{"type":"object","properties":{"healthy":{"type":"boolean","description":"Indicates whether the service is healthy.","example":true},"message":{"type":"string","description":"Additional information about the service health.","example":"Service is healthy"}},"required":["healthy","message"]}},"required":["data"]},"MetaResponse":{"type":"object","description":"Service metadata and attribution information for the Classification API.","properties":{"data":{"type":"object","properties":{"attribution":{"type":"object","description":"Attribution and informational text about the API.","properties":{"title":{"type":"string","description":"Title or name of the API service.","example":"Classification API"},"body":{"type":"string","description":"Descriptive text explaining the service purpose or usage.","example":"This service provides categorization of incoming data using different models. It analyzes the payload and maps them to standardized taxonomy values."}},"required":["title","body"]}},"required":["attribution"]}},"required":["data"]},"ModelsResponse":{"type":"object","description":"List of available classification models and their version metadata.","properties":{"data":{"type":"array","description":"Collection of Lightcast classification models.","items":{"$ref":"#/components/schemas/ModelMeta"}}},"required":["data"],"example":{"data":[{"modelName":"lot","description":"This is lot classification service","availableVersions":[{"version":"7.15.0","taxonomies":{"lot":"7.15"},"releaseDate":"2026-03-30 22:23:37","deprecationDate":"2026-05-29 22:23:37"}]},{"modelName":"company","description":"This is company classification service","availableVersions":[{"version":"2.89.0","taxonomies":{"companies":"2.89.0"},"releaseDate":"2026-03-30 22:23:37","deprecationDate":"2026-05-29 22:23:37"}]}]}},"ModelMeta":{"type":"object","additionalProperties":false,"properties":{"modelName":{"type":"string","description":"Name of the classification model.","example":"lot"},"description":{"type":"string","description":"Short description of the model.","example":"This is lot classification service"},"availableVersions":{"type":"array","description":"Versions available for this model.","items":{"$ref":"#/components/schemas/SimpleVersionMeta"}}},"required":["modelName","description","availableVersions"]},"SimpleVersionMeta":{"type":"object","additionalProperties":false,"properties":{"version":{"type":"string","description":"Model version identifier.","example":"7.9.0"},"taxonomies":{"description":"Taxonomy information or null if unavailable.","oneOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"releaseDate":{"type":"string","description":"ISO-8601 or datetime string when the version was released.","example":"2023-07-14T16:08:51Z"},"deprecationDate":{"type":"string","description":"ISO-8601 or datetime string when the version will be deprecated.","example":"2023-09-12T16:08:51Z"}},"required":["version","taxonomies","releaseDate","deprecationDate"]},"ModelMetaResponse":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/ModelMeta"}},"required":["data"]},"ModelVersionsResponse":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SimpleVersionMeta"}}},"required":["data"]},"ModelVersionResponse":{"type":"object","description":"Detailed metadata for a specific model version, including input and output schema definitions.","properties":{"data":{"type":"object","properties":{"taxonomies":{"description":"Taxonomy information or null if unavailable.","oneOf":[{"type":"object","additionalProperties":{"type":"string"}},{"type":"null"}]},"releaseDate":{"type":"string","description":"Datetime string representing when this version was released.","example":"2023-07-14T16:08:51Z"},"deprecationDate":{"type":"string","description":"Datetime string representing when this version will be deprecated.","example":"2023-07-14T16:08:51Z"},"input":{"type":"object","description":"Schema describing the expected input fields for this model version.","properties":{"type":{"type":"string","example":"object"},"required":{"type":"array","items":{"type":"string"},"example":["country","language","title","description"]},"properties":{"type":"object","additionalProperties":{"description":"Arbitrary JSON Schema fragment describing this input property.","oneOf":[{"type":"object","additionalProperties":true},{"type":"boolean"},{"type":"null"}]}}}},"output":{"type":"object","description":"Schema describing the output fields returned by this model version.","properties":{"type":{"type":"string","example":"object"},"required":{"type":"array","items":{"type":"string"},"example":["specOccId","confidenceScore"]},"properties":{"type":"object","additionalProperties":{"description":"Arbitrary JSON Schema fragment describing this output property.","oneOf":[{"type":"object","additionalProperties":true},{"type":"boolean"},{"type":"null"}]}}}}},"required":["releaseDate","deprecationDate","input","output"]}},"required":["data"]},"SetsResponse":{"type":"object","description":"List of available predefined classification model sets and their latest version metadata.","properties":{"data":{"type":"array","description":"Collection of predefined classification model sets.","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the predefined classification model set.","example":"posting"},"latestVersion":{"type":"string","description":"Latest version of the predefined classification model set.","example":"2026.7"},"locales":{"type":"array","description":"Locales available for the model set.","items":{"type":"string","description":"Locale of the predefined classification model set.","example":["en-US","en-CA","es-ES","fr-FR","de-DE","pt-PT","it-IT","nl-NL"]}},"input":{"type":"array","description":"Input fields accepted by the predefined classification model set.","items":{"type":"string","description":"Input field name for the predefined classification model set.","example":["inputLocale","company","title","description"]}},"output":{"type":"array","description":"Outputs available for the model set.","items":{"type":"string","description":"Output of the predefined classification model set.","example":["benefits","lot","cip","contract","experience","employment","internship","remote","salary","skills","titles"]}}},"required":["name","latestVersion","locales","input","output"]}}},"required":["data"]},"LatestSetResponse":{"type":"object","description":"Metadata for the latest version of a specific predefined classification model set.","properties":{"data":{"type":"object","properties":{"name":{"type":"string","description":"Name of the predefined classification model set.","example":"posting"},"latestVersion":{"type":"string","description":"Latest version of the predefined classification model set.","example":"2026.7"},"locales":{"type":"array","description":"Locales available for the model set.","items":{"type":"string","description":"Locale of the predefined classification model set.","example":["en-US","en-CA","es-ES","fr-FR","de-DE","pt-PT","it-IT","nl-NL"]}},"input":{"type":"array","description":"Input fields accepted by the predefined classification model set.","items":{"type":"string","description":"Input field name for the predefined classification model set.","example":["inputLocale","company","title","description"]}},"output":{"type":"array","description":"Outputs available for the model set.","items":{"type":"string","description":"Output of the predefined classification model set.","example":["benefits","lot","cip","contract","experience","employment","internship","remote","salary","skills","titles"]}}},"required":["name","latestVersion","locales","input","output"]}},"required":["data"]},"SetVersionsResponse":{"type":"object","additionalProperties":false,"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SetVersion"}}},"required":["data"]},"SetVersionResponse":{"type":"object","additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/SetVersion"}},"required":["data"]},"ApiResponseWithErrors":{"type":"object","additionalProperties":false,"properties":{"data":{},"errors":{"$ref":"#/components/schemas/ExecutionErrors"}},"required":["data","errors"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","examples":["Invalid Request","Forbidden","Not Found","Method Not Allowed","Internal Server Error"]},"status":{"type":"integer","description":"HTTP status code for this error response.","examples":[400,403,404,405,500]},"detail":{"description":"Error detail. Validation errors may be an array of strings; panic recovery may return an empty string.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["title","status","detail"]},"GatewayErrorResponse":{"type":"object","additionalProperties":false,"description":"Error response returned by the API gateway before requests reach this service.","properties":{"message":{"type":"string","examples":["Verification failed"]}},"required":["message"]},"ExecutionErrors":{"type":"object","description":"Recoverable model execution errors keyed by model request name or set output name.","additionalProperties":{"type":"array","items":{"type":"string"}},"examples":[{},{"salary":["failed to classify"]}]},"SetVersion":{"type":"object","properties":{"name":{"type":"string","description":"Name of the model set.","example":"posting"},"version":{"type":"string","description":"Version of the model set.","example":"2026.7"},"locales":{"type":"array","description":"Locales available for the model set.","items":{"type":"string","description":"Locale of the predefined classification model set.","example":["en-US","en-CA","es-ES","fr-FR","de-DE","pt-PT","it-IT","nl-NL"]}},"input":{"type":"array","description":"Input fields accepted by the model set.","items":{"type":"string","description":"Input field name for the model set.","example":["inputLocale","company","title","description"]}},"output":{"type":"array","description":"Outputs available for the model set.","items":{"type":"string","description":"Output of the model set.","example":["benefits","lot","cip","contract","experience","employment","internship","remote","salary","skills","titles"]}},"models":{"type":"array","description":"Collection of models included in the model set.","items":{"type":"object","properties":{"modelName":{"type":"string","description":"Name of the model.","example":"lot"},"modelVersion":{"type":"string","description":"Version of the model.","example":"7.9.0"}}}}},"required":["name","version","locales","input","output","models"]},"SetClassifyRequest":{"type":"object","additionalProperties":false,"properties":{"version":{"type":"string","description":"Set version. Defaults to the latest version when omitted.","enum":["2026.7"]},"input":{"$ref":"#/components/schemas/PostingSetClassifyInput"}},"required":["input"]},"PostingSetClassifyInput":{"type":"object","additionalProperties":false,"allOf":[{"if":{"not":{"required":["outputs"]}},"then":{"required":["company","title","description"]}},{"if":{"required":["outputs"],"properties":{"outputs":{"contains":{"enum":["company","naicsStandard"]}}}},"then":{"required":["company"]}},{"if":{"required":["outputs"],"properties":{"outputs":{"contains":{"not":{"enum":["company","naicsStandard"]}}}}},"then":{"required":["title","description"]}}],"properties":{"company":{"type":"string","minLength":1,"description":"Company name. Required when requesting `company` or `naicsStandard`."},"title":{"type":"string","minLength":1,"description":"Posting title. Required for non-company outputs."},"description":{"type":"string","minLength":1,"description":"Posting description. Required for non-company outputs."},"inputLocale":{"type":"string","example":["en-US","en-CA","es-ES","fr-FR","de-DE","pt-PT","it-IT","nl-NL"],"description":"Input locale. Defaults to `en-US` when omitted."},"outputs":{"type":"array","minItems":1,"description":"Requested output keys. Defaults to every output configured by the set when omitted.","items":{"type":"string","examples":["benefits","lot","cip","contract","experience","employment","internship","remote","salary","skills","titles"]}}}},"SetClassifyResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponseWithErrors"},{"type":"object","description":"The response returned after executing the model set.","properties":{"data":{"type":"object","properties":{"result":{"type":"object","description":"Mapping of output identifiers to their individual classification results.","additionalProperties":{"description":"The output from a specific model. Each model defines its own output structure.","oneOf":[{"type":"object"},{"type":"array"}]}},"meta":{"type":"object","description":"Meta data for the model set.","properties":{"setName":{"type":"string","description":"Name of the model set.","example":"posting"},"setVersion":{"type":"string","description":"Version of the model set.","example":"2026.7"}},"required":["setName","setVersion"]}},"required":["result","meta"]},"errors":{"type":"object","description":"Errors encountered during the classification."}},"required":["data","errors"]}]},"ClassifyRequest":{"type":"object","description":"Defines a workflow of one or more models to be executed in sequence, where model inputs can reference other parts of the request.","properties":{"context":{"oneOf":[{"type":"object","description":"Arbitrary key-value data available to all models in the workflow.","additionalProperties":true},{"type":"null"}]},"models":{"type":"object","description":"A map of named models and their configuration.","additionalProperties":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"The identifier of the model to run."},"version":{"type":"string","minLength":1,"description":"The version of the model to use."},"input":{"type":"object","description":"Input parameters passed to the model. May include references to other values in the request using JSONPath.","additionalProperties":true}},"required":["model","version","input"]}}},"required":["models"]},"ClassifyResponse":{"allOf":[{"$ref":"#/components/schemas/ApiResponseWithErrors"},{"type":"object","description":"The response returned after executing one or more models. Each key under `data.result` corresponds to a model from the request and contains that model’s output.","properties":{"data":{"type":"object","properties":{"result":{"type":"object","description":"Mapping of model identifiers to their individual outputs.","additionalProperties":{"description":"The output from a specific model. Each model defines its own output structure.","oneOf":[{"type":"object"},{"type":"array"}]}}},"required":["result"]},"errors":{"type":"object","description":"Errors encountered during classification."}},"required":["data","errors"]}]}}}}