Skip to main content

​
CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

​
Project Overview

Sevalla API documentation site built with Mintlify. Endpoint pages are generated from remote OpenAPI specs. There are no local MDX files per endpoint.

​
Architecture

  • Remote OpenAPI specs (source of truth for all endpoint details, schemas, and examples), served by the production API:
    • https://api.sevalla.com/v3/openapi.json: v3 primary endpoints
    • https://api.sevalla.com/v2/openapi.json: v2 legacy endpoints
  • The specs are generated by mk-app-management-service with @fastify/swagger (src/web/apiGateway/v3/ and src/web/apiGateway/v2/). Change endpoint summaries, descriptions, schemas, and examples there, not in this repo.
  • docs.json: Mintlify configuration (navigation tabs, theme, integrations, navbar, footer). Each tab has an openapi field pointing to a remote spec. An endpoint appears on the site only if a navigation group lists it as "<METHOD> <path>", for example "GET /applications/{id}/egress-ips". Endpoints that are in the spec but not in docs.json are not published.
  • v3/: hand-written guide pages (authentication, errors, rate limits, pagination, CLI, webhook events). They are listed in docs.json like any other page.
  • index.mdx: standalone landing page

​
Development

There is no build step or package.json. Mintlify handles rendering and hosting. To preview locally and check links, install the Mintlify CLI and run:
The preview reads the prod specs. To preview an endpoint that is only on dev so far, temporarily point the tab’s openapi.source at https://api-dev.sevalla.com/v3/openapi.json (or v2). Revert it before committing.

​
Adding a New Endpoint

  1. Add the route and its schema in mk-app-management-service (src/web/apiGateway/v3/ or v2/).
  2. Add "<METHOD> <path>" to the matching group in docs.json, under the right tab. The method and path must match the spec exactly, including parameter names such as {id}.
  3. Merge only after the endpoint is in the prod spec. Check with curl -s https://api.sevalla.com/v3/openapi.json.

​
Conventions

  • All API endpoints use Bearer token authentication
  • Navigation uses two tabs (v3 and v2) with a top-left switcher
  • Commit messages follow conventional commits: feat(scope): description
  • Never use em dashes (—) in any content. Use periods, commas, or rephrase instead
  • Write copy that sounds human and direct. Avoid generic AI-sounding filler phrases
  • Always use TypeScript for code examples, never Python or other languages