Reference

OpenAPI and Swagger

The OpenAPI 3.1 document is compiled from the same operation contracts as REST, GraphQL, gRPC, SDKs, CLI, MCP, and dashboard actions.

RESTREST controller atlasEvery controller-backed endpoint with parameters, request examples, responses, errors, and samples.RESTREST API modelBase URLs, resource conventions, pagination, idempotency, error envelopes, OpenAPI discovery, and examples.GraphQLGraphQL referenceCompiled SDL, query and mutation shapes, pagination, filters, subscriptions, errors, and examples.SDKSDK method referenceEvery client method across TypeScript, Python, C#, Go, and Rust with inputs, returns, and errors.

OpenAPI is not a separate hand-written spec. Vadyl compiles it from canonical resource contracts, route descriptors, request/response schemas, response sets, auth requirements, grants, idempotency policy, and exposure bindings. Swagger UI, Postman, gateways, and client generators should treat this as the project's authoritative REST spec.

Discovery endpoints

GET /api/openapi.json
GET /api/openapi.yaml
GET /api/ContractProjection/descriptor
GET /api/Introspection/surface

Download the spec

openapi-download.example

curl https://api.vadyl.app/v1/openapi.json \
  -H "Authorization: Bearer $VADYL_TOKEN" \
  -H "X-Vadyl-Tenant: acme" \
  -H "X-Vadyl-Project: billing" \
  -o vadyl.openapi.json

Operation ID rules

Operation IDs are stable across protocol projections and follow the canonical operation name. Entity operations use names like Entity.Order.List, platform operations use their owning resource, and route-tail disambiguators are appended when one resource has multiple operations of the same kind.

Schema coverage

Schema family	Included shapes
Entities	Read model, create input, update input, upsert input, filters, sort, pagination, alternate keys.
Operations	Request/response contracts for custom operations, authored handlers, scheduling, storage, analytics, automation, agent runs.
Errors	Canonical error envelope with code, reasonCode, field, retryability, correlationId, explainUrl.
Security	Bearer, API key/service credential, MCP bearer, webhook HMAC management docs, tenant/project headers.
Webhooks	Endpoint/receiver/delivery management routes; event payloads are also documented in webhook docs.

Swagger UI

# Self-hosted Swagger UI
docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON_URL=https://api.vadyl.app/v1/openapi.json \
  swaggerapi/swagger-ui

# Or import into Postman:
postman import vadyl.openapi.json

Generate a client from OpenAPI

Official SDKs are preferred because they also understand publication manifests and Vadyl-specific retry/idempotency policy, but any OpenAPI 3.1 tool can consume the spec.

openapi-generator-cli generate \
  -i vadyl.openapi.json \
  -g typescript-fetch \
  -o ./generated/vadyl-openapi-client

Validation and drift

The OpenAPI generator consumes the same compiled surface as the API dispatcher. Route drift, raw response-code arrays, and unbacked route constants are caught by structural tests before publication.

REST API

GraphQL