Community-driven rewrite of the 42 School Intra API as a proper OpenAPI 3.1 specification, with auto-generated, published clients for Go, Python, and TypeScript.

The original Intra API documentation predates OpenAPI tooling and offers no machine-readable contract, no generated clients, and inconsistent or missing details on required roles, scopes, and response shapes. This project rebuilds the spec endpoint by endpoint, verifying each one against real responses, and ships ready-to-use client libraries generated directly from that spec.

The rendered API reference (built with Scalar) is published from the docs/ directory. It includes custom conventions on top of the base spec:

Progress on rewriting each endpoint is tracked in openapi-rewrite-progress.md.

.
├── specs/           # Source of truth: modular OpenAPI fragments (paths, schemas, parameters)
├── openapi/         # Bundled, released OpenAPI contract (generated from specs/)
├── clients/         # Generated API clients, one per language
│   ├── go/
│   ├── python/
│   └── typescript/
├── docs/            # Scalar-based API reference site + custom plugins
├── tool/            # Build tooling (index generation, versioning scripts)
└── .github/         # CI/CD workflows

The hand-maintained source of the API contract. Split into three concerns to keep large resources manageable:

• paths/ — one directory per resource (e.g. users, closes, coalitions), each containing the path definitions and operations for that resource.
• schemas/ — one directory per resource, containing the data models. Shared types (e.g. error.yaml) live at the top level.
• parameters/ — reusable parameters (pagination, filtering, sorting) shared across operations.

Each directory contains an auto-generated _index.yaml that aggregates its contents. The root specs/openapi.yaml holds the top-level OpenAPI metadata — info, servers, security schemes.

The bundled, single-file OpenAPI document produced from specs/, versioned and released independently via semantic-release. This is the artifact consumers and code generators actually depend on.

Each client is generated from the bundled spec in openapi/ and released independently:

Each client directory is self-contained (own Dockerfile, config.yaml, .releaserc.json) and can be regenerated and released independently of the others.

The Scalar-based documentation site (index.html) plus a custom Scalar plugin (scalar-required-roles-plugin.js) that renders the 🔑/👤 role and scope requirements directly on each operation page, matching Scalar's native styling.

All spec bundling, linting, and client generation runs inside Docker containers via the Makefile — you don't need Go, Python, or Node installed locally to contribute to the spec itself. The only requirement is:

• Docker

Toolchain versions for local development on the clients themselves (if you need to work inside clients/go, clients/python, or clients/typescript directly) are pinned via Nix flakes (flake.nix / .envrc with direnv), which provisions Node.js, Go, and Python automatically when entering the project directory.

Contributions are welcome!

To contribute, edit the relevant files under specs/ — this is the source of truth for the API contract (paths, schemas, and parameters).

Once you've made your changes, run:

make all

This regenerates the index files, bundles the spec, and lints the result — confirming that openapi/openapi.yaml is valid.

Then, regenerate the clients:

make generate-clients

This updates the Go, Python, and TypeScript clients under clients/ to match your spec changes. You can also generate a single client individually with make generate-go, make generate-python, or make generate-typescript.

Before opening a pull request:

• Update openapi-rewrite-progress.md to reflect the status of the endpoint(s) you worked on.
• Run make ci-check to confirm your generated files are fully in sync with your spec changes — this is the same check CI runs, so a clean local run means CI won't flag drift.

Commits must follow the Angular Commit Message Conventions:

• Use feat when adding a new path.
• Use fix when updating an existing path or schema.

Once everything looks good, open a pull request.

This is an unofficial, community project and is not affiliated with or endorsed by 42/Le Réseau. It documents the public-facing behavior of the Intra API as observed; some endpoints, fields, or access rules may be incomplete, inferred, or subject to change without notice on 42's side.

See LICENSE.