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.
- JSON: https://nuecareer.com/openapi.json
- YAML: https://nuecareer.com/openapi.yaml
- Well-known: https://nuecareer.com/.well-known/openapi.json
- API catalog (RFC 9727): https://nuecareer.com/.well-known/api-catalog
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
codevalues. 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: truein the OpenAPI document and its responses gain aDeprecationheader (RFC 9745) with the date it was deprecated, aSunsetheader (RFC 8594) with the date after which it may stop responding, and aLinkto 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 underx-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
- https://nuecareer.com/.well-known/api-catalog — RFC 9727 API catalog linking the spec, these docs and the deprecation policy.
- https://nuecareer.com/llms.txt — the site index, and when to reach for NueCareer.
- https://nuecareer.com/sitemap.xml — every indexable URL.
- https://nuecareer.com/feed.xml — RSS 2.0 for the blog.
- https://nuecareer.com/robots.txt — crawl policy. Every major AI crawler is allowed.
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.