OpenAPI Specification

Accessing the Schema

Live Endpoint

On a running Dagy API instance, the OpenAPI schema is available at:

GET /openapi.json

The interactive Swagger UI documentation is available at:

GET /docs

And the ReDoc alternative:

GET /redoc

Generating Offline

To generate the OpenAPI schema file for offline use or documentation publishing:

uv run python scripts/export_openapi.py

This writes the schema to docs/api/openapi.json.

Schema Coverage

The auto-generated schema includes all 114 API endpoints with:

• Request body schemas (from Pydantic models)
• Response schemas (from Pydantic response models)
• Query parameter definitions
• Path parameter definitions
• Authentication requirements
• HTTP status codes and error responses

Using the Schema

Code Generation

Use the OpenAPI schema to generate typed API clients in any language:

# TypeScript (using openapi-typescript-codegen)
npx openapi-typescript-codegen --input docs/api/openapi.json --output src/api

# Python (using openapi-python-client)
openapi-python-client generate --path docs/api/openapi.json

# Go (using oapi-codegen)
oapi-codegen -package api docs/api/openapi.json > api/client.go

API Testing

Import the schema into tools like Postman, Insomnia, or Bruno:

1. Open the API testing tool
2. Import from file, select docs/api/openapi.json
3. All endpoints are imported with request/response examples

Documentation Publishing

The schema can be used with documentation generators:

# Redocly (static HTML docs)
npx @redocly/cli build-docs docs/api/openapi.json -o docs/api/index.html

# Stoplight (hosted docs)
# Upload openapi.json to Stoplight Studio

Keeping the Schema Updated

The schema is generated from the FastAPI app code. Whenever endpoints or models change, regenerate the schema:

uv run python scripts/export_openapi.py

Consider adding this to your CI/CD pipeline to ensure the schema stays in sync with the codebase.