> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aviatrix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Api reference

# Doc Type: API Reference

> **Tier**: Reference | **Reader phase**: Refining & Details\
> **Back to tier overview**: [reference/index.md](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

| Persona | How they use it |
| - | - |
| **Developer** | Primary audience. Uses to build integrations and automations |
| **Engineer** | Uses when implementing a Configuration Guide via the API modality |

***

## 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](../frontmatter.md) for field definitions and formatting rules.

Use `Aviatrix REST API` or `Getting Started with the Aviatrix API` as the title.

```yaml theme={null}
---
title: "Aviatrix REST API"
description: "Reference for the Aviatrix REST API — authentication, base URL, conventions, and the full endpoint reference."
---
```

***

## Mintlify components

See [Style Guide](../style-guide.md) 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

| Do | Don't |
| - | - |
| Include a working authentication example as the first code block | Describe authentication in prose without a code example |
| Keep hand-authored pages focused on entry points and authentication | Re-document endpoints that will be covered by the generated reference |
| Note controller-specific URL construction clearly | Assume the reader knows the controller is the API host |
| Document error code meanings and resolutions | Leave developers to interpret raw HTTP status codes |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.