Developers

NueCareer API documentation for developers and agents

The NueCareer API is a free, keyless, read-only REST API over the NueCareer career directory: 1,731 U.S. occupations built from O*NET 31.0, BLS OEWS May 2025 wages, BLS Employment Projections 2025-2035 and BEA Regional Price Parities 2024. It is the same data behind the public occupation pages at https://nuecareer.com/careers, in JSON.

When to use the NueCareer API

Reach for it when you need grounded U.S. occupational facts rather than a guess:

  • Pay for a specific job, nationally or in one state, at a named percentile rather than a single "average".
  • Whether a job is growing or shrinking through 2034, and how many openings a year it actually produces.
  • What it takes to get in: typical entry education, O*NET job zone, on-the-job training, day-to-day tasks, skills and knowledge areas.
  • Building a shortlist against constraints — "pays over $70,000, no bachelor’s degree required, remote-friendly" — in one request instead of scraping a directory.
  • Automation exposure, before advising somebody to enter or leave a field.
  • Resolving a messy job title to a canonical occupation, using O*NET alternate titles.

It is deliberately not for:

  • Job listings or vacancies. There are none in this dataset.
  • Salaries outside the United States. Every wage figure here is BLS, so it is U.S.-only.
  • Personal, account, résumé or subscription data. None of it is exposed, at any endpoint, with any credential.
  • Calling the free AI tools programmatically. Those are rate-limited HTML forms for people; send a person the URL instead.

Quick start

No key, no signup, no headers required.

curl "https://nuecareer.com/api/v1/careers?q=nurse&limit=3"
curl "https://nuecareer.com/api/v1/careers/registered-nurse?include=salary_by_state"
curl "https://nuecareer.com/api/v1/collections/highest-paying-trades"

Start from https://nuecareer.com/api/v1 for a machine-readable index of every endpoint.

OpenAPI description

An OpenAPI 3.1 document describes the whole surface, with a unique operationId, a prose description and typed schemas on every operation — enough to load straight into a function-calling tool definition.

Every API response also carries a Link header pointing at the spec (rel="service-desc"), these docs (rel="service-doc"), the API catalog (rel="api-catalog") and the deprecation policy (rel="deprecation"), so a client holding only a response can find all four.

Endpoints

Operation Method and path What it returns
getApiIndex GET /api/v1 The endpoint index, rate limit, dataset vintage and OpenAPI URL.
searchCareers GET /api/v1/careers Occupations matching a text query and filters, with total-count pagination.
getCareerBySlug GET /api/v1/careers/{slug} One occupation in full.
listCareerCollections GET /api/v1/collections Curated shortlists such as "highest-paying trades".
getCareerCollection GET /api/v1/collections/{slug} One collection with its ranked members.
listCareerTools GET /api/v1/tools Catalogue of the free career tools and their page URLs.

Searching occupations

GET /api/v1/careers accepts:

Parameter Type Meaning
q string Free text over titles, O*NET alternate titles and descriptions. Exact and prefix title matches rank first.
category string Restrict to one category slug, taken from any result’s categorySlug.
facet string, repeatable Require a derived characteristic. ANDed when repeated.
min_salary / max_salary number Bound the national median annual wage, in USD.
min_growth number Minimum BLS projected percent employment change, 2025-2035. Pass 0 to drop declining occupations.
education string Exact match on the BLS typical entry-level education string.
sort string One of relevance, median_wage_desc, median_wage_asc, growth_desc, openings_desc, ai_resilience_desc, title_asc.
limit integer 1 to 100. Defaults to 20.
offset integer Items to skip. Page against pagination.total.

Valid facet values: noDegreeRequired, trade, remoteFriendly, outdoor, physical, helpsPeople, creative, analytical, worksWithAnimals, lowStress, paysWell, fastGrowing, declining, brightOutlook.

Fetching one occupation

GET /api/v1/careers/{slug} returns a compact record by default. The heavy parts are opt-in through include, repeatable or comma-separated: salary_by_state, tasks, skills, personality, narrative.

salary_by_state adds all 54 U.S. jurisdictions with a BEA cost-of-living-adjusted median. skills adds the O*NET skill, knowledge, ability, work-style, software and work-context inventories. personality adds fit scores for all 16 MBTI types — a NueCareer-derived figure, not a government one.

Listing collections, tools and endpoints

Endpoint Parameter Meaning
GET /api/v1/collections q Optional. Case-insensitive match on collection title, slug and description.
GET /api/v1/tools category Optional. One of the key values in the response’s categories.
GET /api/v1/tools kind Optional. ai, calculator, quiz or explorer.
GET /api/v1 tag Optional. Careers, Collections, Tools or Meta; narrows the endpoint list.

Authentication

The NueCareer API has no authentication, and there is nothing to authenticate to. Do not send an Authorization header, a cookie or an API key to /api/v1; every endpoint is public, read-only, and holds no user data. There are no write operations and no webhooks.

Rate limits

120 requests per 10 minutes per IP address, shared across all /api/v1 endpoints, in fixed windows. Every response, success or error, reports where you stand so you can throttle yourself before you ever hit the limit:

Header Example Meaning
RateLimit-Policy "public-api";q=120;w=600 The policy, in the IETF RateLimit structured-field format: quota q per window of w seconds.
RateLimit "public-api";r=117;t=412 Requests remaining r, and seconds t until the window resets.
RateLimit-Limit 120 Quota per window.
RateLimit-Remaining 117 Requests left in this window.
RateLimit-Reset 412 Seconds until the window resets (delta-seconds, not a timestamp).
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset The same three values under the legacy names. Reset is delta-seconds here too.
Retry-After 412 Sent with HTTP 429 only: seconds to wait before retrying.

Over the limit you get HTTP 429 with code: "rate_limited" and a Retry-After header. Wait that many seconds, then retry; do not retry sooner. Responses are CDN-cached for 24 hours, so repeating an identical request usually costs you nothing. A response served from the cache repeats the rate-limit headers of the request that filled the cache; treat them as an upper bound on your own usage, since cache hits are not counted.

Versioning and deprecation

The NueCareer API is versioned in the URL path. The current major version is v1, served under /api/v1, and it is the only version.

  • Within a major version, changes are additive only: new endpoints, new optional parameters, new response fields, new code values. Write clients that ignore fields they do not recognise.
  • Breaking changes ship only under a new major path (/api/v2): removing or renaming a field, changing its type or meaning, making an optional parameter required, or removing an endpoint. The previous major version keeps running alongside the new one.
  • Nothing is removed without notice. A deprecated endpoint is marked deprecated: true in the OpenAPI document and its responses gain a Deprecation header (RFC 9745) with the date it was deprecated, a Sunset header (RFC 8594) with the date after which it may stop responding, and a Link to the migration notes. The sunset date is at least 6 months after the deprecation date, and the change is dated in the changelog below.
  • Every response already carries Link: <…/developers#versioning-and-deprecation>; rel="deprecation" pointing at this policy, and the OpenAPI document states it under x-api-lifecycle.

Changelog

  • v1 — current. No endpoint is deprecated and no sunset is scheduled.

Errors

Every non-2xx response from /api/v1 is JSON in one envelope. HTML is never returned, for any status, including 404 and 405.

{
  "error": "No occupation matches the slug \"registered-nurses\".",
  "code": "not_found",
  "message": "No occupation matches the slug \"registered-nurses\".",
  "hint": "Search for the right slug with GET https://nuecareer.com/api/v1/careers?q=registered%20nurses.",
  "status": 404,
  "docs": "https://nuecareer.com/developers#errors",
  "parameter": "slug"
}

Branch on code, never on message. hint always names the next action — a corrected value, or the endpoint that lists the valid ones. error duplicates message and exists only for older clients.

code Status Meaning
bad_request 400 The request could not be understood at all.
invalid_parameter 400 A named query or path parameter was malformed or had an unknown value. parameter names it.
not_found 404 The path is valid but nothing is served at it, or the slug does not exist.
method_not_allowed 405 The endpoint exists but does not accept that HTTP verb. The Allow header lists the ones it does.
unauthorized 401 The endpoint requires a signed-in session. No public endpoint returns this.
forbidden 403 Authenticated, but not permitted.
rate_limited 429 Too many requests from this IP inside the window.
unsupported_media_type 415 The request body was not in a format the endpoint accepts.
internal_error 500 Something failed on our side. Safe to retry.

The full list of codes is also enumerated in the OpenAPI document: bad_request, invalid_parameter, not_found, method_not_allowed, unauthorized, forbidden, rate_limited, unsupported_media_type, internal_error.

Markdown representations

Every public page on this domain answers Accept: text/markdown with a CommonMark representation of itself, per acceptmarkdown.com, and sets Vary: Accept so a shared cache cannot hand you the wrong one.

curl -H "Accept: text/markdown" https://nuecareer.com/careers/registered-nurse

The same documents are reachable by URL suffix if you would rather not negotiate: https://nuecareer.com/index.md, https://nuecareer.com/developers.md, https://nuecareer.com/api.md, https://nuecareer.com/agents.md, and .md on any career, tool or blog URL.

Other machine-readable files

Data licence and attribution

O*NET-derived fields are used under CC BY 4.0. Every API response carries the required attribution in its attribution object; reproduce it if you redistribute the data. BLS and BEA figures are U.S. public domain (17 U.S.C. 105). Personality-fit and AI-resilience scores are NueCareer-derived, not government figures, and are labelled as such wherever they appear. Full derivation rules: https://nuecareer.com/careers/methodology.

Contact

hello at nuecareer dot com. Tell us what you are building — if the API is missing a field you need, it is usually already in the bank.