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

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

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