---
title: "NueCareer for developers and agents"
description: "Free, keyless REST API over 923 U.S. occupations with BLS wages and projections. OpenAPI 3.1 description, JSON errors, and markdown representations of every page."
canonical: "https://nuecareer.com/developers"
---

# NueCareer for developers and agents

NueCareer publishes a free, keyless, read-only HTTP API over its career directory: 923 U.S.
occupations built from O*NET 30.3, BLS OEWS May 2025 wages, BLS Employment Projections
2024-2034 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.

```bash
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

## 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, 2024-2034. 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.

## Authentication

There is none, 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.

## Rate limits

120 requests per 10 minutes per IP address, shared across all `/api/v1` endpoints. Over the
limit you get HTTP 429 with `code: "rate_limited"`. Responses are CDN-cached for 24 hours, so
repeating an identical request usually costs you nothing.

## Errors

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

```json
{
  "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](https://acceptmarkdown.com), and sets
`Vary: Accept` so a shared cache cannot hand you the wrong one.

```bash
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/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](https://creativecommons.org/licenses/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@nuecareer.com. Tell us what you are building — if the API is missing a field you need,
it is usually already in the bank.