Skip to main content

​
Doc Type: API Reference

Tier: Reference | Reader phase: Refining & Details
Back to tier overview: reference/index.md

​
What it is

The API Reference documents the Aviatrix REST API: its endpoints, request parameters, response schemas, authentication, and error codes. It is the authoritative source for developers integrating with or automating Aviatrix programmatically. The API Reference is generated from the OpenAPI specification (compiled_openapi.json) and rendered via the Mintlify API reference feature. Hand-authored pages in this category serve as entry points, authentication guides, and supplementary conceptual context — not manual duplications of the generated endpoint documentation.

​
Goal

After reading an API Reference document, the reader can authenticate with the Aviatrix API and make their first successful request. They understand the API conventions well enough to build integrations or automations without guessing at request structure or error handling.

​
Primary personas

​
When to create a hand-authored API Reference document

The generated OpenAPI reference handles endpoint-level documentation automatically. Create a hand-authored document when:
  • Authentication — The authentication flow requires explanation beyond what an OpenAPI spec captures (token acquisition, session management, controller-specific behavior)
  • Getting Started — A guide helping developers make their first API call and understand the API conventions
  • Versioning — When the API has versioning behavior that affects how clients should be written
  • Error Reference — A consolidated guide to error codes and their meaning/resolution, if not fully captured in the OpenAPI spec
Do not hand-author endpoint documentation that is already covered by the generated reference.

​
Required sections — API Overview / Getting Started

  1. Overview — 3–5 sentences: what the API covers, what operations it supports, and the base URL pattern.
  2. Authentication — How to authenticate API requests: where to obtain credentials, how to pass them (header, token format), and session/token expiry behavior. Include a working curl or Python example.
  3. Base URL — The pattern for constructing the controller URL. Note that this is controller-specific (not a hosted endpoint).
  4. Conventions — API-wide conventions the developer must know: date formats, pagination patterns, rate limits, response envelope structure.
  5. API Explorer — The rendered OpenAPI reference, embedded on this page via the Mintlify API reference feature.

​
Tone & voice

Technical and example-driven. API documentation readers learn from examples. Every concept should be accompanied by a code block showing it in practice. Keep prose minimal — use it to explain why, let code show how.

​
Length guidance

60–150 lines for hand-authored pages. The bulk of the reference is generated — hand-authored pages should be focused entry points, not comprehensive manuals.

​
Frontmatter

See Frontmatter Standards for field definitions and formatting rules. Use Aviatrix REST API or Getting Started with the Aviatrix API as the title.

​
Mintlify components

See Style Guide for component definitions and usage rules. Use bash/python/json code blocks for authentication examples and request/response samples, and tables for error codes. Keep pages focused — the bulk of the reference is generated from the OpenAPI spec.

​
Linking

  • Link in from: Configuration Guides (API tab), Developer-facing landing pages
  • Link out to: No fixed link-out — the rendered OpenAPI reference is embedded within these pages, not linked to externally

​
Dos and don’ts