# Niuro Public Jobs API

Read-only discovery for Niuro’s currently published roles.

- Developer portal: <https://niuro.io/developers/>
- OpenAPI 3.1 description: <https://niuro.io/openapi.json>
- RFC 9727 API catalog: <https://niuro.io/.well-known/api-catalog>

## Endpoint

`GET https://niuro.io/api/v1/jobs/`

- Authentication: none
- Response media type: `application/json`
- Request body: none
- Optional query: `limit`, an integer from 1 to 100
- Upstream source: `https://app.niuro.io/api/public/jobs`

## Successful response

The endpoint returns an envelope with `success: true` and a `jobs` array.
Each job can include:

- `title`: public role title
- `description`: public role description
- `slug`: stable identifier used by the public job URL
- `publicUrl`: canonical application URL on `app.niuro.io`
- `seniority`: seniority label
- `requiredSkills`: array of skill names
- `modality`: working model, such as remote
- `location`: public eligibility or location label
- `publishedAt`: publication timestamp when available
- compensation fields when the role publishes them

Fields can be absent when a role does not publish that information. Clients
should ignore unknown fields and must not infer unpublished compensation,
location, or eligibility.

## Errors

The versioned endpoint returns RFC 9457 Problem Details as
`application/problem+json`. Problems include `type`, `title`, `status`, `detail`,
`instance`, a stable `code`, and a `resolution` link. A 429 includes
`Retry-After`; an upstream outage returns a no-store 503.

Unknown paths below `/api/` return the same JSON problem format rather than an
HTML error page.

## Rate limits

The Worker enforces 100 requests per 60 seconds per client IP at each Cloudflare
location. Responses publish `RateLimit-Policy` and the configured limit; a 429
publishes zero remaining quota plus `Retry-After`. Cloudflare counters are eventually consistent across
locations, so these headers are throttling guidance rather than a global quota
guarantee.

## Versioning and deprecation

The stable contract uses URL-path versioning at `/api/v1/`. Additive fields can
appear within v1, and clients must ignore unknown properties. Breaking changes
use a new major path such as `/api/v2/`.

Niuro documents deprecation before emitting the standardized `Deprecation`
header and provides at least 90 days before a published `Sunset` date. Version 1
is current and emits neither lifecycle header today. The complete policy is at
<https://niuro.io/docs/api-lifecycle.md>.

## Usage

Use the feed to discover active roles and direct people to each job’s
`publicUrl`. Applications happen through that URL; this feed does not accept
applications. Poll responsibly and treat a role’s absence from the latest
successful response as closed or unavailable.

Human-readable jobs are available at <https://niuro.io/jobs/>.