Skip to main content

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.

​
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

APIPurposeAuth
Business APIInteract 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 APICreate a new organization and bank account on QontoDedicated 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

ScriptCommandWhen to use
npm run bundleBundles .github/.oas_src/business_api.yml → api-reference/business-api/openapi.yml using Redocly, then appends a do-not-edit warningAfter any OpenAPI source change
npm run watchWatches source files and auto-runs bundle on changeDuring active OpenAPI development
npm run testBundles + validates the spec with Spectral lintingBefore submitting a PR
npm run lintRuns yamllint on all YAML filesBefore submitting a PR
npm run previewBundles + starts a Redocly preview serverQuick OpenAPI-only preview
npm run htmlBundles + builds a static HTML file to _build/index.htmlOne-off static build
npm run cleanRemoves _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: 
---
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

ProblemFix
mint dev fails to startRun mintlify install to reinstall CLI dependencies
Page shows as 404Ensure the page is listed in docs.json and the .mdx file exists
Bundle errorsRun npm run test to see Spectral validation details
Changes not reflected in browserMake sure you’re editing source files (not openapi.yml); re-run npm run bundle
YAML linting errorsRun npm run lint; check .yamllint.yml for rules (2-space indent, etc.)
$ref resolution errorsVerify paths in business_api.yml are correct relative to repo root