Full OpenAPI spec

The complete machine-readable API definition — 116+ endpoints, all request/response schemas, authentication, error codes.

VelaOS publishes an OpenAPI 3.1 spec at https://api.velaos.ch/openapi.yaml. It's the authoritative reference — everything on this site and in the SDK is generated from it.

Using the spec

Swagger UI / Redoc

View it interactively at api.velaos.ch/docs. You can authenticate with your API key and try any endpoint live.

Postman / Insomnia

Import the spec URL directly. Both tools generate an organized collection with every endpoint, example payloads, and environment variables for your API key.

# Download the raw spec
curl https://api.velaos.ch/openapi.yaml > velaos-openapi.yaml

Code generation

Generate typed SDK clients in any language:

# TypeScript
npx openapi-typescript https://api.velaos.ch/openapi.yaml -o src/velaos.d.ts

# Go
oapi-codegen -package velaos https://api.velaos.ch/openapi.yaml > velaos.go

# Python
openapi-python-client generate --url https://api.velaos.ch/openapi.yaml

Authentication

All endpoints under /api/v1/ require either a session cookie (console) or an X-API-Key header. See Authentication for details.

Versioning

The spec is versioned alongside the API. Current version: v2.1.0. Breaking changes between major versions are listed in Breaking changes. The info.version field in the spec file is the source of truth.

LLM / AI agent use

The spec is structured for machine consumption. Combined with the policy JSON Schema at GET /policies/schema, an LLM can generate valid policies from natural language and call the API to apply them. Our llms.txt contains curated prompts and examples.