API fundamentals

Use the dagy.io API to deploy Python workflows, start and inspect runs, manage workspace configuration, and connect orchestration to your application. A successful run submission gives you a run identifier; follow that run to learn whether the work succeeded.

On this page

Base URL and headers Choose an API area Response conventions Lists and pagination Make reliable requests

Start with Connect to your workspace to obtain credentials. For an end-to-end deployment, follow Deploy and release a flow.

Base URL and headers

The CLI's hosted API default is https://api.dagy.io/app. Keep the /app prefix. If your workspace uses a different endpoint, use the complete API base URL provided for that workspace. Paths in this reference are relative to that base URL.

Shell

export DAGY_API_URL="https://api.dagy.io/app"
# Supply a valid key or session token through your secret manager.
export DAGY_TOKEN="YOUR_TOKEN"

curl --fail-with-body "$DAGY_API_URL/me" \
  -H "Authorization: Bearer $DAGY_TOKEN"

DAGY_TOKEN is a variable used by these curl examples. The CLI uses its saved credentials; setting this variable does not sign the CLI in.

Header	Use
`Authorization: Bearer …`	Required for authenticated operations; accepts a Dagy API key, Dagy access token, or configured sign-in token.
`Content-Type: application/json`	Send when the request contains JSON.
`X-Org-Id`	Select a workspace for a session with multiple memberships. API keys remain bound to their own workspace.
`X-Request-Id`	An optional identifier you generate and retain for support. It is not an idempotency key.

Use HTTPS for remote requests. Preserve opaque resource identifiers, tokens, and artifact locators exactly as returned. Percent-encode path segments and query values. Do not infer permissions from the format of an identifier.

Choose an API area

Goal	Reference
Sign in, create keys, choose permissions	Authentication
Manage workspaces, membership, and audit history	Workspace administration
Register versions, upload artifacts, change deployments	Flows and deployments
Start, inspect, cancel, retry, or compare runs	Runs
Create recurring or one-time execution	Schedules
Configure runtime values and credentials	Environments, secrets
Set up integrations	Saved connectors, cloud connections
Trigger from external events or send alerts	Events, notifications
Discover datasets and inspect data controls	Catalog and lineage, data quality, approvals
Build or revise a flow with AI	AI Studio
Track consumption	Usage and billing

The endpoint index lists the supported customer surface. The OpenAPI reference provides request models, query parameters, typed responses, and field defaults. Some responses contain open-ended objects; the guides explain how to interpret them. A field named artifact_s3_uri, for example, is a returned artifact locator, not a requirement to configure storage yourself.

Response conventions

Most successful reads and updates return 200. Resource creation may return 200 or 201, depending on the operation. Asynchronous operations such as dependency packaging return 202; ordinary run submission currently returns 200 with a run status. Successful deletes may return a JSON status object, null, or 204 without a body. Follow the endpoint's contract.

Many optional fields can be null. Timestamps are generally ISO 8601 strings, while token expiry and scheduling fields explicitly named *_epoch use Unix seconds. Run log timestamps can also be numeric milliseconds; inspect the event format before formatting them.

Lists and pagination

Collection	Behavior
`GET /flows`	`items` plus opaque `next_token`; `limit` defaults to `100` and must be positive.
`GET /runs/{run_id}/logs`	`events` plus optional `next_token`; live pages default to `500` events.
`GET /deployments`	`items`; default `limit=100`, maximum `500`; no continuation token.
`GET /runs`	`items`; optional `limit` is clamped to `1–500`; omitting it does not impose this bound. Filter by `flow_name`, `since`, and `environment`.
Other lists	Consult the operation. Many return a bounded `items` array without pagination.

For cursor-based operations, send the returned next_token unchanged on the next request with the same filters. Stop when no token is returned. Filtering and grouping can produce a short or empty flow page that still has a next token. Do not treat page length as completion or reuse a token with another endpoint.

Make reliable requests

Check HTTP status before parsing a response as success. Record the request path, time, status, and request/run identifier, while redacting credentials and sensitive payloads. Follow Errors and retries.

The API does not offer a universal idempotency header. Repeating a run submission can start another run. After an uncertain write, inspect the corresponding resource or run list before retrying. Design external writes performed by your flows to tolerate retries.

Features that require workspace enablement can be unavailable even when their routes appear in the reference. Usage and billing distinguishes implemented account capabilities from unavailable payment workflows.