API Overview

Base URL

The API is served from a single AWS Lambda function via API Gateway. The base URL depends on your deployment:

https://api.dagy.io/app

For local development, the default is http://localhost:8000.

Authentication

All endpoints (except /health, /billing/plans, /billing/webhook, and /webhooks/{token}) require authentication. Dagy supports three authentication methods:

Access Tokens: Obtained via POST /auth/login. Include in requests as:

Authorization: Bearer <access_token>

API Keys: Created via POST /api-keys with scoped permissions. Include as:

Authorization: Bearer dagy_<key>

JWT Tokens: When DAGY_JWT_REQUIRED=true, the API validates JWTs against the configured JWKS URL. Include as:

Authorization: Bearer <jwt>

See the Authentication Guide for full details.

RBAC (Role-Based Access Control)

Every authenticated request resolves to an identity with a role. Dagy enforces permissions on all endpoints:

Role	Description
owner	Full access — the only role with any billing.* or admin.org permission
admin	Everything except billing and org-level settings (billing.*, admin.org)
developer	Read/write/trigger on flows, runs, schedules, nodes, dep-packages, connectors; read-only on secrets/environments
viewer	Read-only across flows, runs, schedules, nodes, environments, dep-packages, connectors

The full 4-role × 30-permission matrix (generated from src/dagy_api/auth.py) is in Auth. When a request lacks the required permission, the API returns 403 Forbidden.

Rate Limiting

All authenticated endpoints are rate-limited using a token-bucket algorithm:

• 120 requests per minute per API key or IP address
• 200 burst capacity
• Excluded endpoints: /health, /docs, /openapi.json

Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per minute
X-RateLimit-Remaining	Requests remaining in current window
Retry-After	Seconds to wait (only on 429 responses)

Request Format

All request bodies must be JSON with Content-Type: application/json. Query parameters are used for filtering and pagination.

Response Format

All responses are JSON. Successful responses return the resource directly. Error responses follow the standard format:

{
  "detail": "Human-readable error message"
}

Pagination

List endpoints support cursor-based pagination:

• limit: Maximum items to return (default: 100)
• next_token: Opaque cursor from a previous response

{
  "items": [...],
  "next_token": "opaque-cursor-string"
}

When next_token is null or absent, there are no more pages.

Triggering Model

Flow runs can be triggered in four ways:

1. API run trigger: POST /runs with deployment or flow name
2. Schedule-managed trigger: Automatic via scheduler tick (cron, interval)
3. Manual schedule trigger: POST /schedules/{schedule_id}/trigger
4. Webhook trigger: POST /webhooks/{token} from external systems via sensors

Event Processing

The API uses SQS for asynchronous event processing. Run triggers are enqueued and processed by the Lambda SQS consumer. Supported event types:

• flow_trigger: Execute a flow run
• scheduler_tick: Process due schedules
• run_status_poll: Poll async backend status (Step Functions, ECS)
• run_status_update: Update run status and trigger notifications

Endpoint Categories

The API is organized into these categories (see Endpoints Reference for full details):

Category	Endpoints	Description
Authentication	2	Login, logout
User	2	Current user identity and profile
Flows	8	Register, list, versions, latest, get, delete, deploy, backends
Deployments	5	Create, list, rollback, change version, delete
Runs	5	Trigger, list, get, cancel, logs
Scheduling	5	CRUD + manual trigger + partial update
API Keys	3	Create, list, delete
Organizations	6	Org CRUD, members, roles
DAG Drafts	6	Visual builder drafts + node types
Usage & Billing	10	Metering, quotas, Stripe
Audit Logs	2	Query audit trail
Secrets	6	Encrypted secret management
Notifications	9	Channels + alert rules
Environments	12	CRUD, variables, reorder, diff, promote
Sensors	6	Event triggers + webhooks
Artifacts	3	Multipart upload (initiate, complete, abort)
UI Config	4	Marketing, navigation, dashboard, settings
AI Studio	17	Session-based agentic workflow building and attachments
Super Admin	16	Customer management, exceptions, impersonation
Health	2	Health checks

The table above is an approximate grouping; the authoritative, always-current count comes from the generated OpenAPI spec.

Total (from docs/api/openapi.json): 126 unique paths / 168 operations.

Regenerate the spec and these counts with:

uv run python scripts/generate_openapi.py

OpenAPI Specification

The canonical OpenAPI schema is auto-generated by FastAPI. Generate it with:

uv run python scripts/generate_openapi.py

This writes the schema to docs/api/openapi.json (and --check fails if it is stale — wire it into CI). You can also access it at /openapi.json on a running API instance.