incus-api-docs

--- name: incus-api-docs description: Provides access to the dynamically generated Incus OpenAPI specification via localized query scripts. Use when the user asks to integrate, fix, or understand Incus API endpoints, schemas, or response types. --- # Incus API Documentation This skill allows you to efficiently query the Incus REST API specification, which is served dynamically by the development proxy at `http://localhost:3001/documentation/rest-api.yaml`. Incus event stream semantics are documented separately from the OpenAPI spec. When working with `/1.0/events`, lifecycle events, operation events, logging events, or event-backed cache invalidation, read `http://localhost:3001/documentation/_sources/events.md.txt` before implementing changes. ## ⚠️ MANDATORY: Check Before Implementation **You MUST use this skill BEFORE implementing any new API integration or modifying existing ones.** Never assume the shape of an API response or request body. The Incus API has specific behaviors (e.g., sync vs async responses, specific metadata structures) that must be verified first. ## Core Workflow (Progressive Disclosure) The API specification is very large. To keep your context lean and avoid token bloat, do not read the entire spec. Instead, follow this modular workflow: 1. **Discover**: If you need to find an endpoint or definition name, load and follow instructions in [references/search.md](references/search.md). 2. **Explore Endpoints**: If you know the endpoint path but need details (methods, parameters, or response types), load and follow instructions in [references/endpoint.md](references/endpoint.md). 3. **Inspect Schemas**: If you encounter a schema reference (e.g., `#/definitions/Instance`) and need its exact structure, load and follow instructions in [references/definition.md](references/definition.md). 4. **Check Shared Responses**: If an endpoint refers to a shared response type (e.g., `#/responses/BadRequest`), load and follow instructions in [references/response.md](references/response.md). ## Critical Implementation Rule: Autogenerated Examples The Incus API spec is autogenerated, resulting in **very general example responses** within endpoint documentation. These examples often lack the specific structure required for implementation. - **Rule**: Never trust the literal shape of example objects provided in the [endpoint documentation](references/endpoint.md). - **Mandate**: Always use [get-definition.ts](references/definition.md) to fetch the formal schema definitions for any object you need to handle. The formal definitions are the only source of truth.