# Nextstep Job Tracker — API documentation

The documented integration surface is a read-only, public REST API at the same origin as Nextstep. It describes the job application tracker and provides fictional sandbox data. It does not provide access to real applications, accounts, administrator settings or assistant messages. The private APIs used by the web application remain authenticated and are outside this public contract.

## Endpoints

- [GET /api/v1/capabilities](https://nextstep.fans/api/v1/capabilities): Product name, description, features and documentation URLs
- [GET /api/v1/stages](https://nextstep.fans/api/v1/stages): Application stages and assessment statuses used by the tracker
- [GET /api/v1/sandbox/applications](https://nextstep.fans/api/v1/sandbox/applications): Fictional applications; optional integer limit between 1 and 3, default 3
- [GET /api/v1/health](https://nextstep.fans/api/v1/health): Database availability: status ok or unavailable

## Example request and response

```sh
curl -fsS -H 'Accept: application/json' 'https://nextstep.fans/api/v1/sandbox/applications?limit=1'

{"sandbox":true,"applications":[{"id":"sample-1","company":"Example Studio","role":"Product Designer","status":"Applied","workMode":"Remote"}]}
```

## Authentication, errors and capacity

Public endpoints require no authentication and accept GET and HEAD. Unsupported methods return 405 with an Allow header. Invalid limit values return 400 with a typed JSON error containing code, message and the compatible error field. Unknown resources return 404. During server draining the API can return 503 with Retry-After. The public API allows 300 requests per 60-second window per client network and server process, shared across versioned and legacy URLs. RateLimit-Policy and RateLimit describe the quota and remaining capacity on every public API response. A 429 includes Retry-After in seconds. Cache metadata, avoid polling sample data and honour retry guidance; availability is not guaranteed. Session-protected workspace endpoints return 401 when signed out. API keys and a delegated authorization flow are not available.

## Markdown and discovery

Request the homepage or any documentation page with Accept: text/markdown to receive Markdown; Accept: text/html returns HTML. Negotiated responses include Vary: Accept. Explicit .md URLs are also available. The sitemap lists indexable pages, and llms.txt links to agent-readable resources. OpenAPI operation IDs, typed parameters and response schemas can be used to generate read-only tools; no tool is authorized to mutate a user’s workspace through this public API.

- [OpenAPI specification](https://nextstep.fans/openapi.json): OpenAPI 3.1, JSON format
- [Versioning and deprecation](https://nextstep.fans/docs/versioning): Version 1 compatibility and retirement policy
- [Errors and rate limits](https://nextstep.fans/docs/errors): Typed failures, quota headers and retry guidance
- [Authentication](https://nextstep.fans/docs/authentication): Public access and private workspace boundaries
- [Nextstep CLI](https://nextstep.fans/cli): Official source CLI and release status
- [Developer portal](https://nextstep.fans/developers): Quickstart and sandbox
- [Agent instructions](https://nextstep.fans/agent-instructions): Use cases and boundaries