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

# 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:

.mdx files — prose pages, guides, or API reference pages
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:

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

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:

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):

---
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:

{
  "group": "My Category",
  "pages": [
    "api-reference/business-api/my-category/my-resource/list"
  ]
}

(No .mdx extension in docs.json.)

5. Test locally

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:

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:

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

Introduction

AGENTS

Qonto Public Documentation

Repository Overview

The Two APIs

Running Locally

NPM Scripts

Repository Structure

How Mintlify Works

API Reference Pages

Adding a New Endpoint (Step-by-Step)

1. Add the OpenAPI definition

2. Bundle the spec

3. Create the `.mdx` reference page

4. Add the page to `docs.json`

5. Test locally

Adding a New OAuth Scope

Naming Rules (enforced)

How to add

Automation

Troubleshooting

​Qonto Public Documentation

​Repository Overview

​The Two APIs

​Running Locally

​NPM Scripts

​Repository Structure

​How Mintlify Works

​API Reference Pages

​Adding a New Endpoint (Step-by-Step)

​1. Add the OpenAPI definition

​2. Bundle the spec

​3. Create the .mdx reference page

​4. Add the page to docs.json

​5. Test locally

​Adding a New OAuth Scope

​Naming Rules (enforced)

​How to add

​Automation

​Troubleshooting

Qonto Public Documentation

Repository Overview

The Two APIs

Running Locally

NPM Scripts

Repository Structure

How Mintlify Works

API Reference Pages

Adding a New Endpoint (Step-by-Step)

1. Add the OpenAPI definition

2. Bundle the spec

3. Create the `.mdx` reference page

4. Add the page to `docs.json`

5. Test locally

Adding a New OAuth Scope

Naming Rules (enforced)

How to add

Automation

Troubleshooting