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 including billing and org management
admin	All permissions except billing.write
developer	Read, write, and trigger flows/runs/schedules
viewer	Read-only access to flows, runs, and schedules

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

Total: 128 endpoints

OpenAPI Specification

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

uv run python scripts/export_openapi.py

This writes the schema to docs/api/openapi.json. You can also access it at /openapi.json on a running API instance.