Skip to content

API Reference

The dagctl API gives you programmatic control over every part of the platform: creating and managing projects, configuring jobs and schedules, reviewing and approving deployment plans, managing your team, and exporting execution data to your own systems.

In This Section

  • Projects — Create, update, deploy, and delete SQLMesh and dbt projects
  • Jobs — Configure scheduled jobs, trigger manual runs, and retrieve logs
  • Plans — List, approve, reject, cancel, and retry deployment plans
  • Team — Manage organization members, roles, and invitations
  • Environment Variables — Create and manage secrets and config values injected into job pods
  • Environment Protection — Restrict access to sensitive environments (e.g. prod)
  • Execution Metrics — Job runs, model executions, daily stats, and per-model performance
  • Examples — Polling scripts, SLA checks, and regression detection

Authentication

All API requests require two headers:

Header Value Description
Authorization Bearer dctl_... API token generated from your organization settings
X-Organization-ID org-xxxxxxxx Your organization ID

Creating an API Token

Generate a token from the dagctl web UI under Settings > Authentication, then select the API Tokens tab and click Create Token. The token is displayed once — copy it immediately.

Note

API tokens have full organization access. Store them securely and rotate them periodically.

Example Request

curl -s "https://api.dagctl.io/api/v1/projects/${PROJECT_ID}/runs?limit=10" \
  -H "Authorization: Bearer ${DAGCTL_TOKEN}" \
  -H "X-Organization-ID: ${ORG_ID}"

Base URL

All endpoints are prefixed with /api/v1.

Conventions

Pagination

Paginated endpoints accept page and limit query parameters:

Parameter Type Default Max Description
page integer 1 - Page number (1-indexed)
limit integer varies 500 Results per page

Paginated responses include:

{
  "total": 142,
  "page": 1,
  "limit": 50,
  "total_pages": 3
}

Date Formats

Format Used For Example
RFC3339 Timestamps and updated_after filter 2026-02-26T00:00:00Z
YYYY-MM-DD Date range filters (start_date, end_date) 2026-02-26

Nullable Fields and omitempty

Nullable fields are omitted from the JSON response when their value is null. They do not appear as "field": null — the key is absent entirely.

Fields affected by this behavior:

  • cronjob_name — absent for manually triggered runs
  • end_time — absent for in-progress runs
  • duration_seconds — absent for in-progress runs
  • error_message — absent when no error occurred
  • pod_name — absent before pod scheduling

Your polling client should handle missing keys, not null values.