{
  "openapi": "3.1.0",
  "info": {
    "title": "NueCareer Public API",
    "version": "1.0.0",
    "summary": "Keyless read access to a 923-occupation career directory built on U.S. federal data.",
    "description": "The NueCareer Public API exposes the same occupation data that powers the public career\ndirectory at https://nuecareer.com/careers: BLS OEWS May 2025 wages (national and by state,\nwith BEA cost-of-living adjustment), BLS Employment Projections 2024-2034, O*NET 30.3 interest,\nskill, task and work-context profiles, and NueCareer-derived personality-fit and AI-resilience\nscores.\n\n## When to use this API\n\nReach for it when you need grounded U.S. occupational facts rather than a guess:\n\n- What a specific job pays nationally or in one state, at a named percentile.\n- Whether an occupation is projected to grow or shrink through 2034, and how many openings a year.\n- What education, job zone, skills, knowledge areas or day-to-day tasks an occupation requires.\n- Building a shortlist against constraints: \"pays over $70k, no bachelor’s degree, remote-friendly\".\n- Checking how exposed an occupation is to automation before advising someone to enter it.\n\nDo not use it for job listings (it has none), for salary data outside the United States, or as a\nsource of personal or account data (it holds none).\n\n## Authentication\n\nNone. Every endpoint here is public and read-only. Do not send credentials.\n\n## Rate limits\n\n120 requests per 10 minutes per IP address, shared across every `/api/v1` endpoint. Exceeding\nit returns HTTP 429 with `code: \"rate_limited\"`. Responses are CDN-cached for 24 hours, so\nrepeated identical requests generally do not count against you.\n\n## Errors\n\nEvery non-2xx response is JSON in a single envelope with a stable `code`, a human `message`,\nand a `hint` naming the next action. HTML is never returned from `/api/v1`.\n\n## Data licence\n\nO*NET-derived fields are used under CC BY 4.0 and every response carries the required\nattribution in its `attribution` object; reproduce it if you redistribute the data. BLS and\nBEA figures are U.S. public domain (17 U.S.C. 105). Personality-fit and AI-resilience scores\nare NueCareer-derived and labelled as such.",
    "termsOfService": "https://nuecareer.com/terms",
    "contact": {
      "name": "NueCareer Support",
      "email": "hello@nuecareer.com",
      "url": "https://nuecareer.com/contact"
    },
    "license": {
      "name": "CC BY 4.0 (O*NET-derived fields)",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://nuecareer.com/developers"
  },
  "servers": [
    {
      "url": "https://nuecareer.com/api/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Careers",
      "description": "Occupation search and lookup over the federal career bank."
    },
    {
      "name": "Collections",
      "description": "Curated occupation shortlists such as \"highest-paying trades\"."
    },
    {
      "name": "Tools",
      "description": "Catalogue of the free, no-account career tools on the site."
    },
    {
      "name": "Meta",
      "description": "Service discovery and dataset provenance."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "List the available endpoints",
        "description": "Returns a machine-readable index of every endpoint in this API, the URL of this OpenAPI document, the current rate limit, and the vintage of the underlying federal datasets. Call this first if you are discovering the API at runtime.",
        "tags": [
          "Meta"
        ],
        "responses": {
          "200": {
            "description": "The service index.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "name",
                    "endpoints"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Service name."
                    },
                    "description": {
                      "type": "string",
                      "description": "What the service is for."
                    },
                    "version": {
                      "type": "string",
                      "description": "API version served at this path."
                    },
                    "documentation": {
                      "type": "string",
                      "format": "uri",
                      "description": "Human-readable developer docs."
                    },
                    "openapi": {
                      "type": "string",
                      "format": "uri",
                      "description": "This OpenAPI document."
                    },
                    "authentication": {
                      "type": "string",
                      "description": "Authentication scheme, or \"none\"."
                    },
                    "rateLimit": {
                      "type": "string",
                      "description": "Rate limit in plain language."
                    },
                    "endpoints": {
                      "type": "array",
                      "description": "Every callable endpoint, with a one-line description.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "method": {
                            "type": "string",
                            "description": "HTTP method."
                          },
                          "path": {
                            "type": "string",
                            "description": "Path relative to the server URL."
                          },
                          "operationId": {
                            "type": "string",
                            "description": "Matches the operationId in the OpenAPI document."
                          },
                          "description": {
                            "type": "string",
                            "description": "What the endpoint returns."
                          }
                        }
                      }
                    },
                    "dataset": {
                      "type": "object",
                      "description": "Vintage and size of the underlying federal datasets.",
                      "properties": {
                        "occupations": {
                          "type": "integer",
                          "description": "Number of occupations in the bank."
                        },
                        "buildDate": {
                          "type": "string",
                          "description": "ISO date the bank was last built."
                        },
                        "sources": {
                          "type": "array",
                          "description": "Federal releases the bank is derived from.",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/careers": {
      "get": {
        "operationId": "searchCareers",
        "summary": "Search and filter occupations",
        "description": "Searches the 923-occupation bank by free text and filters it by category, derived facets, wage floor or ceiling, projected growth and typical entry education. Returns a compact summary per occupation plus total-count pagination. Use this to resolve a job title to a slug before calling getCareerBySlug, or to build a constrained shortlist.",
        "tags": [
          "Careers"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Free-text search over occupation titles, O*NET alternate titles and the one-sentence description. Case-insensitive substring match; exact and prefix title matches rank highest.",
            "schema": {
              "type": "string",
              "maxLength": 120
            },
            "example": "nurse"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Restrict to one occupational category, given as its slug (the `categorySlug` field of any result), e.g. \"healthcare-practitioners-and-technical\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "facet",
            "in": "query",
            "required": false,
            "description": "Require a derived characteristic to be true. Repeat the parameter to require several (they are ANDed), or pass a comma-separated list.",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "noDegreeRequired",
                  "trade",
                  "remoteFriendly",
                  "outdoor",
                  "physical",
                  "helpsPeople",
                  "creative",
                  "analytical",
                  "worksWithAnimals",
                  "lowStress",
                  "paysWell",
                  "fastGrowing",
                  "declining",
                  "brightOutlook"
                ]
              }
            },
            "example": [
              "remoteFriendly",
              "noDegreeRequired"
            ]
          },
          {
            "name": "min_salary",
            "in": "query",
            "required": false,
            "description": "Exclude occupations whose national median annual wage is below this figure, in USD. Occupations with no published median are excluded by this filter.",
            "schema": {
              "type": "number",
              "minimum": 0
            },
            "example": 70000
          },
          {
            "name": "max_salary",
            "in": "query",
            "required": false,
            "description": "Exclude occupations whose national median annual wage is above this figure, in USD.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "min_growth",
            "in": "query",
            "required": false,
            "description": "Exclude occupations whose BLS projected 2024-2034 percent employment change is below this figure. Pass 0 to exclude declining occupations.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "education",
            "in": "query",
            "required": false,
            "description": "Exact, case-insensitive match on the BLS typical entry-level education string, e.g. \"Bachelor’s degree\" or \"High school diploma or equivalent\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Result ordering. \"relevance\" ranks by text match then median wage, and is the default; it is only meaningful together with `q`.",
            "schema": {
              "type": "string",
              "enum": [
                "relevance",
                "median_wage_desc",
                "median_wage_asc",
                "growth_desc",
                "openings_desc",
                "ai_resilience_desc",
                "title_asc"
              ],
              "default": "relevance"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum occupations to return in this page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Number of matching occupations to skip. Use with `limit` to page through `pagination.total`.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 5000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching occupations, most relevant first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "pagination",
                    "attribution"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "description": "The matching occupations for this page.",
                      "items": {
                        "$ref": "#/components/schemas/OccupationSummary"
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "attribution": {
                      "$ref": "#/components/schemas/Attribution"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A query parameter was malformed or had an unknown value. `hint` names the valid values.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/careers/{slug}": {
      "get": {
        "operationId": "getCareerBySlug",
        "summary": "Get one occupation in full",
        "description": "Returns the complete public record for one occupation: national wage percentiles, employment projections, education and job zone, derived facets and RIASEC interest profile. Large sub-objects are opt-in through `include` so the default response stays small.",
        "tags": [
          "Careers"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The occupation identifier, lowercase kebab-case, e.g. \"registered-nurse\". Obtain one from searchCareers.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "maxLength": 120
            },
            "example": "registered-nurse"
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Optional sub-objects to add to the response. Repeat the parameter or pass a comma-separated list. `salary_by_state` adds median and quartile wages for all 54 U.S. jurisdictions, including a cost-of-living-adjusted median. `tasks` adds the O*NET day-to-day task statements. `skills` adds O*NET skills, knowledge, abilities, work styles, software and work context. `personality` adds fit scores for all 16 MBTI types (NueCareer-derived). `narrative` adds the BLS Occupational Outlook Handbook prose sections.",
            "explode": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "salary_by_state",
                  "tasks",
                  "skills",
                  "personality",
                  "narrative"
                ]
              }
            },
            "example": [
              "salary_by_state"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "The occupation record.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "attribution"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/OccupationDetail"
                    },
                    "attribution": {
                      "$ref": "#/components/schemas/Attribution"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The slug was not valid kebab-case, or an `include` value was unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No occupation has that slug. `hint` gives a search URL to find the right one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/collections": {
      "get": {
        "operationId": "listCareerCollections",
        "summary": "List curated occupation collections",
        "description": "Returns every curated shortlist (\"highest-paying trades\", \"AI-resistant careers\", \"jobs that help people\", …) with its slug and member count. Use this when the question is a shortlist rather than a lookup.",
        "tags": [
          "Collections"
        ],
        "responses": {
          "200": {
            "description": "Every available collection.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "attribution"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string",
                            "description": "Collection identifier for getCareerCollection."
                          },
                          "title": {
                            "type": "string",
                            "description": "Display title."
                          },
                          "description": {
                            "type": "string",
                            "description": "What the collection selects for."
                          },
                          "memberCount": {
                            "type": "integer",
                            "description": "Number of occupations in the collection."
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Human-readable page."
                          },
                          "apiUrl": {
                            "type": "string",
                            "format": "uri",
                            "description": "Detail endpoint."
                          }
                        }
                      }
                    },
                    "attribution": {
                      "$ref": "#/components/schemas/Attribution"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/collections/{slug}": {
      "get": {
        "operationId": "getCareerCollection",
        "summary": "Get one collection with its member occupations",
        "description": "Returns a curated collection together with the full ranked list of occupations in it, each as an occupation summary.",
        "tags": [
          "Collections"
        ],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Collection identifier from listCareerCollections, e.g. \"highest-paying-trades\".",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "maxLength": 120
            },
            "example": "highest-paying-trades"
          }
        ],
        "responses": {
          "200": {
            "description": "The collection and its members.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "attribution"
                  ],
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "slug",
                        "title",
                        "members"
                      ],
                      "properties": {
                        "slug": {
                          "type": "string",
                          "description": "Collection identifier."
                        },
                        "title": {
                          "type": "string",
                          "description": "Display title."
                        },
                        "description": {
                          "type": "string",
                          "description": "What the collection selects for."
                        },
                        "url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Human-readable page."
                        },
                        "members": {
                          "type": "array",
                          "description": "Occupations in the collection, in the collection’s own ranking order.",
                          "items": {
                            "$ref": "#/components/schemas/OccupationSummary"
                          }
                        }
                      }
                    },
                    "attribution": {
                      "$ref": "#/components/schemas/Attribution"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The slug was not valid kebab-case.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No collection has that slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/tools": {
      "get": {
        "operationId": "listCareerTools",
        "summary": "List the free career tools",
        "description": "Returns the catalogue of free, no-account career tools on the site (resume, interview, salary and letter helpers) with the URL of each tool page. Discovery only: the tools themselves are AI-backed HTML forms, not API endpoints, so point a person at the URL rather than trying to call it.",
        "tags": [
          "Tools"
        ],
        "responses": {
          "200": {
            "description": "Every live tool, plus the category taxonomy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data",
                    "categories"
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "slug",
                          "title",
                          "url"
                        ],
                        "properties": {
                          "slug": {
                            "type": "string",
                            "description": "Tool identifier, matching its page URL."
                          },
                          "title": {
                            "type": "string",
                            "description": "Tool name."
                          },
                          "description": {
                            "type": "string",
                            "description": "What the tool produces."
                          },
                          "category": {
                            "type": "string",
                            "description": "Category key from `categories`."
                          },
                          "kind": {
                            "type": "string",
                            "enum": [
                              "ai",
                              "calculator",
                              "quiz",
                              "explorer"
                            ],
                            "description": "How the tool works."
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "The tool page."
                          },
                          "datePublished": {
                            "type": "string",
                            "format": "date",
                            "description": "First published."
                          },
                          "dateModified": {
                            "type": "string",
                            "format": "date",
                            "description": "Last substantively updated."
                          }
                        }
                      }
                    },
                    "categories": {
                      "type": "array",
                      "description": "The category taxonomy the `category` field refers to.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string",
                            "description": "Category key."
                          },
                          "label": {
                            "type": "string",
                            "description": "Display label."
                          },
                          "description": {
                            "type": "string",
                            "description": "What the category covers."
                          }
                        }
                      }
                    },
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The error envelope returned by every endpoint for every non-2xx status. Never HTML.",
        "required": [
          "error",
          "code",
          "message",
          "hint",
          "status",
          "docs"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable failure message. Same text as `message`; kept for older clients."
          },
          "code": {
            "type": "string",
            "enum": [
              "bad_request",
              "invalid_parameter",
              "not_found",
              "method_not_allowed",
              "unauthorized",
              "forbidden",
              "rate_limited",
              "unsupported_media_type",
              "internal_error"
            ],
            "description": "Stable machine-readable error code. Branch on this, not on the message text."
          },
          "message": {
            "type": "string",
            "description": "Human-readable failure message."
          },
          "hint": {
            "type": "string",
            "description": "What to do next to succeed — a corrected parameter value, or the endpoint that lists valid ones."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code, repeated in the body."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "URL of the error documentation."
          },
          "parameter": {
            "type": "string",
            "description": "Name of the offending parameter, when exactly one parameter is at fault."
          }
        }
      },
      "OccupationSummary": {
        "type": "object",
        "description": "One occupation as returned by list endpoints: enough to rank and choose, not the full record.",
        "required": [
          "slug",
          "title",
          "description",
          "category",
          "socCode",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable lowercase kebab-case identifier, e.g. \"registered-nurse\"."
          },
          "title": {
            "type": "string",
            "description": "Occupation title as displayed on the site."
          },
          "description": {
            "type": "string",
            "description": "One-sentence summary of what the occupation does."
          },
          "category": {
            "type": "string",
            "description": "Human-readable occupational category."
          },
          "categorySlug": {
            "type": "string",
            "description": "Slug form of the category, usable as the `category` filter."
          },
          "socCode": {
            "type": "string",
            "description": "BLS Standard Occupational Classification code."
          },
          "onetsocCode": {
            "type": "string",
            "description": "O*NET-SOC code (SOC code plus O*NET detail suffix)."
          },
          "medianAnnualWageUsd": {
            "type": [
              "number",
              "null"
            ],
            "description": "BLS OEWS May 2025 national median annual wage in USD. Null where BLS does not publish one."
          },
          "wageVintage": {
            "type": [
              "string",
              "null"
            ],
            "description": "Release the wage figures come from, e.g. \"OEWS May 2025\"."
          },
          "projectedGrowthPercent": {
            "type": [
              "number",
              "null"
            ],
            "description": "BLS projected percent change in employment, 2024-2034."
          },
          "annualOpenings": {
            "type": [
              "number",
              "null"
            ],
            "description": "BLS projected average annual openings, 2024-2034."
          },
          "typicalEducation": {
            "type": [
              "string",
              "null"
            ],
            "description": "BLS typical entry-level education, e.g. \"Bachelor’s degree\"."
          },
          "jobZone": {
            "type": "integer",
            "description": "O*NET Job Zone, 1 (little preparation) to 5 (extensive)."
          },
          "aiResilienceScore": {
            "type": [
              "number",
              "null"
            ],
            "description": "NueCareer-derived automation-resilience score, 0-100."
          },
          "facets": {
            "type": "object",
            "description": "Boolean characteristics derived from O*NET work context and BLS outlook. `lowStress` is null when O*NET stress-tolerance coverage is insufficient. `aiResilience` is a NueCareer-derived 0-100 score, not a government figure.",
            "properties": {
              "noDegreeRequired": {
                "type": "boolean",
                "description": "Typical entry education is below a bachelor’s degree."
              },
              "trade": {
                "type": "boolean",
                "description": "A skilled trade occupation."
              },
              "remoteFriendly": {
                "type": "boolean",
                "description": "Work context supports remote or hybrid delivery."
              },
              "outdoor": {
                "type": "boolean",
                "description": "Performed primarily outdoors."
              },
              "physical": {
                "type": "boolean",
                "description": "Has substantial physical demands."
              },
              "helpsPeople": {
                "type": "boolean",
                "description": "Direct care, teaching or social-impact work."
              },
              "creative": {
                "type": "boolean",
                "description": "Artistic or design-led work."
              },
              "analytical": {
                "type": "boolean",
                "description": "Analysis- or research-led work."
              },
              "worksWithAnimals": {
                "type": "boolean",
                "description": "Animal-facing work."
              },
              "lowStress": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Low O*NET stress-tolerance requirement. Null when coverage is insufficient."
              },
              "paysWell": {
                "type": "boolean",
                "description": "Median wage above the U.S. median annual wage."
              },
              "fastGrowing": {
                "type": "boolean",
                "description": "BLS projects above-average employment growth, 2024-2034."
              },
              "declining": {
                "type": "boolean",
                "description": "BLS projects declining employment, 2024-2034."
              },
              "brightOutlook": {
                "type": "boolean",
                "description": "Flagged Bright Outlook by O*NET."
              },
              "aiResilience": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "NueCareer-derived automation-resilience score, 0 (most exposed) to 100 (least)."
              }
            }
          },
          "riasec": {
            "type": "object",
            "description": "O*NET RIASEC interest profile, each on the O*NET Occupational Interest scale of 1-7.",
            "properties": {
              "R": {
                "type": "number",
                "description": "Realistic."
              },
              "I": {
                "type": "number",
                "description": "Investigative."
              },
              "A": {
                "type": "number",
                "description": "Artistic."
              },
              "S": {
                "type": "number",
                "description": "Social."
              },
              "E": {
                "type": "number",
                "description": "Enterprising."
              },
              "C": {
                "type": "number",
                "description": "Conventional."
              }
            }
          },
          "topMbtiTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "MBTI types this occupation scores best against. NueCareer-derived, not a government figure."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable occupation page."
          },
          "apiUrl": {
            "type": "string",
            "format": "uri",
            "description": "Detail endpoint for this occupation."
          }
        }
      },
      "OccupationDetail": {
        "type": "object",
        "description": "The full public record for one occupation. Fields marked optional below are present only when requested via `include`.",
        "required": [
          "slug",
          "title",
          "description",
          "category",
          "socCode",
          "education",
          "facets"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "description": "Stable identifier."
          },
          "title": {
            "type": "string",
            "description": "Occupation title as displayed on the site."
          },
          "onetTitle": {
            "type": "string",
            "description": "The occupation’s official O*NET title."
          },
          "alternateTitles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "O*NET alternate job titles people actually use for this role."
          },
          "description": {
            "type": "string",
            "description": "Full O*NET occupation description."
          },
          "category": {
            "type": "string",
            "description": "Human-readable occupational category."
          },
          "categorySlug": {
            "type": "string",
            "description": "Slug form of the category."
          },
          "socCode": {
            "type": "string",
            "description": "BLS SOC code."
          },
          "onetsocCode": {
            "type": "string",
            "description": "O*NET-SOC code."
          },
          "wages": {
            "type": [
              "object",
              "null"
            ],
            "description": "BLS OEWS wage data. Null where BLS publishes none for this occupation.",
            "properties": {
              "vintage": {
                "type": "string",
                "description": "OEWS release the figures come from."
              },
              "national": {
                "type": "object",
                "description": "National wage distribution in USD, plus total employment.",
                "properties": {
                  "employment": {
                    "type": "number",
                    "description": "Total U.S. employment."
                  },
                  "meanAnnual": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Mean annual wage."
                  },
                  "pct10": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "10th percentile annual wage."
                  },
                  "pct25": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "25th percentile annual wage."
                  },
                  "median": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Median (50th percentile) annual wage."
                  },
                  "pct75": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "75th percentile annual wage."
                  },
                  "pct90": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "90th percentile annual wage."
                  },
                  "hourlyMedian": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Median hourly wage."
                  },
                  "topCoded": {
                    "type": "boolean",
                    "description": "True when BLS top-coded a figure at $239,200; the real value is at least that, not exactly it."
                  }
                }
              },
              "byState": {
                "type": "object",
                "description": "Only present with include=salary_by_state. Keyed by two-letter jurisdiction code; `medianColAdjusted` applies BEA Regional Price Parities.",
                "additionalProperties": {
                  "type": "object",
                  "properties": {
                    "employment": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "State employment."
                    },
                    "median": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "State median annual wage."
                    },
                    "pct25": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "State 25th percentile annual wage."
                    },
                    "pct75": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "State 75th percentile annual wage."
                    },
                    "medianColAdjusted": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "description": "State median adjusted for cost of living via BEA RPP 2024."
                    }
                  }
                }
              }
            }
          },
          "outlook": {
            "type": [
              "object",
              "null"
            ],
            "description": "BLS Employment Projections, 2024-2034. Null where BLS publishes none.",
            "properties": {
              "cycle": {
                "type": "string",
                "description": "Projection cycle, e.g. \"2024-2034\"."
              },
              "employmentBase": {
                "type": "number",
                "description": "Employment in the base year."
              },
              "employmentProjected": {
                "type": "number",
                "description": "Projected employment in the target year."
              },
              "changePercent": {
                "type": "number",
                "description": "Percent change over the cycle."
              },
              "changeNumeric": {
                "type": "number",
                "description": "Absolute change in jobs over the cycle."
              },
              "annualOpenings": {
                "type": "number",
                "description": "Projected average annual openings."
              },
              "typicalEducation": {
                "type": "string",
                "description": "Typical entry-level education."
              },
              "workExperience": {
                "type": "string",
                "description": "Work experience in a related occupation."
              },
              "onTheJobTraining": {
                "type": "string",
                "description": "Typical on-the-job training."
              }
            }
          },
          "education": {
            "type": "object",
            "description": "Preparation requirements.",
            "properties": {
              "jobZone": {
                "type": "integer",
                "description": "O*NET Job Zone, 1-5."
              },
              "jobZoneLabel": {
                "type": "string",
                "description": "Plain-language Job Zone label."
              },
              "typicalLevel": {
                "type": "string",
                "description": "BLS typical entry-level education."
              },
              "onetEducation": {
                "type": "array",
                "description": "O*NET distribution of education levels actually held by incumbents.",
                "items": {
                  "type": "object",
                  "properties": {
                    "level": {
                      "type": "string",
                      "description": "Education level."
                    },
                    "percent": {
                      "type": "number",
                      "description": "Percent of incumbents at that level."
                    }
                  }
                }
              }
            }
          },
          "facets": {
            "type": "object",
            "description": "Boolean characteristics derived from O*NET work context and BLS outlook. `lowStress` is null when O*NET stress-tolerance coverage is insufficient. `aiResilience` is a NueCareer-derived 0-100 score, not a government figure.",
            "properties": {
              "noDegreeRequired": {
                "type": "boolean",
                "description": "Typical entry education is below a bachelor’s degree."
              },
              "trade": {
                "type": "boolean",
                "description": "A skilled trade occupation."
              },
              "remoteFriendly": {
                "type": "boolean",
                "description": "Work context supports remote or hybrid delivery."
              },
              "outdoor": {
                "type": "boolean",
                "description": "Performed primarily outdoors."
              },
              "physical": {
                "type": "boolean",
                "description": "Has substantial physical demands."
              },
              "helpsPeople": {
                "type": "boolean",
                "description": "Direct care, teaching or social-impact work."
              },
              "creative": {
                "type": "boolean",
                "description": "Artistic or design-led work."
              },
              "analytical": {
                "type": "boolean",
                "description": "Analysis- or research-led work."
              },
              "worksWithAnimals": {
                "type": "boolean",
                "description": "Animal-facing work."
              },
              "lowStress": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Low O*NET stress-tolerance requirement. Null when coverage is insufficient."
              },
              "paysWell": {
                "type": "boolean",
                "description": "Median wage above the U.S. median annual wage."
              },
              "fastGrowing": {
                "type": "boolean",
                "description": "BLS projects above-average employment growth, 2024-2034."
              },
              "declining": {
                "type": "boolean",
                "description": "BLS projects declining employment, 2024-2034."
              },
              "brightOutlook": {
                "type": "boolean",
                "description": "Flagged Bright Outlook by O*NET."
              },
              "aiResilience": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "NueCareer-derived automation-resilience score, 0 (most exposed) to 100 (least)."
              }
            }
          },
          "interests": {
            "type": "object",
            "description": "O*NET interest profile.",
            "properties": {
              "riasec": {
                "type": "object",
                "description": "O*NET RIASEC interest profile, each on the O*NET Occupational Interest scale of 1-7.",
                "properties": {
                  "R": {
                    "type": "number",
                    "description": "Realistic."
                  },
                  "I": {
                    "type": "number",
                    "description": "Investigative."
                  },
                  "A": {
                    "type": "number",
                    "description": "Artistic."
                  },
                  "S": {
                    "type": "number",
                    "description": "Social."
                  },
                  "E": {
                    "type": "number",
                    "description": "Enterprising."
                  },
                  "C": {
                    "type": "number",
                    "description": "Conventional."
                  }
                }
              },
              "primary": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The one to three dominant RIASEC letters."
              }
            }
          },
          "relatedOccupationSlugs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Slugs of O*NET related occupations, usable directly with getCareerBySlug."
          },
          "tasks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Only present with include=tasks. O*NET day-to-day task statements."
          },
          "personalityFit": {
            "type": "object",
            "description": "Only present with include=personality. NueCareer-derived, not a government figure."
          },
          "narrative": {
            "type": "object",
            "description": "Only present with include=narrative. BLS Occupational Outlook Handbook prose sections."
          },
          "sources": {
            "type": "array",
            "description": "The exact federal releases this record is derived from.",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string",
                  "description": "Dataset name, e.g. \"O*NET\" or \"BLS OEWS\"."
                },
                "version": {
                  "type": "string",
                  "description": "Release version."
                },
                "year": {
                  "type": "string",
                  "description": "Release year."
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Where the release is published."
                }
              }
            }
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable occupation page."
          }
        }
      },
      "Attribution": {
        "type": "object",
        "description": "Source attribution. O*NET data is used under CC BY 4.0 and this notice must travel with any redistribution of it.",
        "required": [
          "text",
          "license",
          "methodology"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The attribution statement to reproduce alongside the data."
          },
          "license": {
            "type": "string",
            "format": "uri",
            "description": "URL of the O*NET data licence."
          },
          "methodology": {
            "type": "string",
            "format": "uri",
            "description": "How the derived scores are computed."
          }
        }
      },
      "Pagination": {
        "type": "object",
        "description": "Offset pagination state for the current response.",
        "required": [
          "limit",
          "offset",
          "total",
          "hasMore"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "description": "Maximum items requested."
          },
          "offset": {
            "type": "integer",
            "description": "Items skipped before the first returned item."
          },
          "total": {
            "type": "integer",
            "description": "Total items matching the query across all pages."
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether a further page exists after this one."
          }
        }
      }
    }
  }
}