> ## Documentation Index > Fetch the complete documentation index at: https://docs.qonto.com/llms.txt > Use this file to discover all available pages before exploring further. # AGENTS # Qonto Public Documentation ## Repository Overview This is a **Mintlify-based documentation site** for Qonto's public APIs. It contains API references, guides, SDK documentation, and developer resources. ### The Two APIs | API | Purpose | Auth | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | **Business API** | Interact with the Qonto product on behalf of an existing organization (read transactions, make transfers, manage cards, etc.) | API Key (mostly read-only) or OAuth | | **Onboarding API** | Create a new organization and bank account on Qonto | Dedicated credentials | **Business API authentication:** * **API Key** — mostly read-only access, simpler setup * **OAuth 2.0** — full read/write access, requires scopes, used for partner integrations acting on behalf of a user *** ## Running Locally ```bash theme={null} # Install dependencies (first time only) npm install brew install yamllint # required for YAML linting npm install -g mintlify # required for full site preview # Start the full documentation site with live reload mint dev ``` `mint dev` automatically opens the browser. All changes to `.mdx` files and the bundled `openapi.yml` are reflected live. **Always verify your changes are visible in the browser before considering work done.** If `mint dev` fails: run `mintlify install` to reinstall dependencies. *** ## NPM Scripts | Script | Command | When to use | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | `npm run bundle` | Bundles `.github/.oas_src/business_api.yml` → `api-reference/business-api/openapi.yml` using Redocly, then appends a do-not-edit warning | After any OpenAPI source change | | `npm run watch` | Watches source files and auto-runs `bundle` on change | During active OpenAPI development | | `npm run test` | Bundles + validates the spec with Spectral linting | Before submitting a PR | | `npm run lint` | Runs yamllint on all YAML files | Before submitting a PR | | `npm run preview` | Bundles + starts a Redocly preview server | Quick OpenAPI-only preview | | `npm run html` | Bundles + builds a static HTML file to `_build/index.html` | One-off static build | | `npm run clean` | Removes `_build/` | Cleanup | > **`mint dev` vs `npm run preview`**: `mint dev` runs the full Mintlify site (all `.mdx` pages, navigation, theme). `npm run preview` is Redocly-only and only shows the OpenAPI spec — use it for quick spec checks. *** ## Repository Structure ``` .github/ ├── .oas_src/ │ └── business_api.yml # 🚫 GENERATED — index of $ref pointers, never edit directly api-reference/ ├── business-api/ │ ├── openapi.yml # 🚫 GENERATED — never edit directly │ ├── components/ │ │ ├── security/ │ │ │ └── schemes.yml # ✏️ OAuth scopes + API key definitions │ │ ├── resources/ # ✏️ Modular endpoint YAML files (one dir per resource) │ │ ├── schemas/ # ✏️ Shared request/response schemas │ │ ├── responses/ # ✏️ Shared response definitions │ │ └── parameters/ # ✏️ Shared parameter definitions │ ├── accounts-organizations/ # ✏️ .mdx reference pages by category │ ├── cards/ │ └── ... ├── onboarding-api/ │ └── onboarding_api.yml # ✏️ Onboarding API spec (self-contained, edit directly) └── sdk-libraries/ # Auto-generated SDK docs get-started/ # ✏️ Guides (authentication, use cases, etc.) docs.json # ✏️ Mintlify navigation + theme config ``` *** ## How Mintlify Works Mintlify renders documentation from two source types: 1. **`.mdx` files** — prose pages, guides, or API reference pages 2. **`docs.json`** — defines the navigation tree, theme, anchors, and which pages appear where ### API Reference Pages Each API endpoint has a minimal `.mdx` file that tells Mintlify which OpenAPI operation to render: ```mdx theme={null} --- openapi: get /v2/bank_accounts --- ``` That's it — Mintlify reads the bundled `openapi.yml` and generates the full reference page (parameters, request/response schemas, playground) automatically. *** ## Adding a New Endpoint (Step-by-Step) ### 1. Add the OpenAPI definition Create or edit the relevant YAML file under `api-reference/business-api/components/resources/`. Each resource has its own directory containing one file per operation (e.g. `list.yml`, `create.yml`, `show.yml`). ``` api-reference/business-api/components/resources/my-resource/list.yml ``` `.github/.oas_src/business_api.yml` is auto-generated — it is just an index of `$ref` pointers rebuilt from the component files. **Never edit it directly.** ### 2. Bundle the spec ```bash theme={null} npm run bundle ``` This regenerates `api-reference/business-api/openapi.yml`. Check for errors — Redocly will surface `$ref` issues and schema problems. Validate the bundled spec: ```bash theme={null} npm run test ``` ### 3. Create the `.mdx` reference page Create a new file under the appropriate category in `api-reference/business-api/`: ``` api-reference/business-api/my-category/my-resource/list.mdx ``` Content (minimal): ```mdx theme={null} --- openapi: get /v2/my_resource --- ``` The value after `openapi:` must match the HTTP method + path exactly as defined in the spec. ### 4. Add the page to `docs.json` Open `docs.json` and add your new `.mdx` page to the correct navigation group under the API Reference anchor: ```json theme={null} { "group": "My Category", "pages": [ "api-reference/business-api/my-category/my-resource/list" ] } ``` (No `.mdx` extension in `docs.json`.) ### 5. Test locally ```bash theme={null} mint dev ``` Navigate to your new page in the browser. Confirm: * The page renders with correct parameters and response schemas * The OAuth scope (if any) is shown correctly * The interactive playground works *** ## Adding a New OAuth Scope OAuth scopes are defined in: ``` api-reference/business-api/components/security/schemes.yml ``` ### Naming Rules (enforced) * **Singular form only** * ❌ `bank_accounts.write` * ✅ `bank_account.write` * **Multi-word resources use snake\_case** * ✅ `internal_transfer.write` * ✅ `sepa_direct_debit.read` * **Object and action separated by `.`** * ✅ `organization.read` * ✅ `card.write` * **Common actions**: `read`, `write`, `trust`, or a specific verb (e.g., `webhook`) ### How to add In `schemes.yml`, add your scope under `flows.authorizationCode.scopes`: ```yaml theme={null} scopes: # existing scopes... my_resource.read: Retrieve my resources my_resource.write: Create and update my resources ``` Then reference the scope in your endpoint definition: ```yaml theme={null} security: - OAuth: - my_resource.read ``` ### Automation A GitHub Actions workflow (`.github/workflows/detect-new-oauth-scopes.yml`) automatically detects new scopes when a PR is merged to `master` and syncs them to the Dev Portal backend. No manual action needed after merge. *** ## Troubleshooting | Problem | Fix | | -------------------------------- | ---------------------------------------------------------------------------------- | | `mint dev` fails to start | Run `mintlify install` to reinstall CLI dependencies | | Page shows as 404 | Ensure the page is listed in `docs.json` and the `.mdx` file exists | | Bundle errors | Run `npm run test` to see Spectral validation details | | Changes not reflected in browser | Make sure you're editing source files (not `openapi.yml`); re-run `npm run bundle` | | YAML linting errors | Run `npm run lint`; check `.yamllint.yml` for rules (2-space indent, etc.) | | `$ref` resolution errors | Verify paths in `business_api.yml` are correct relative to repo root |