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

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.
• Mandate: Always use get-definition.ts to fetch the formal schema definitions for any object you need to handle. The formal definitions are the only source of truth.