Projects API
These endpoints manage the full lifecycle of dagctl projects — SQLMesh and dbt pipelines connected to a Git repository.
GET /api/v1/projects
Returns all projects in your organization.
Response
{
"projects": [
{
"id": "proj_abc123",
"organization_id": "org-xxxxxxxx",
"name": "analytics",
"description": "Core analytics models",
"project_type": "sqlmesh",
"repository_url": "git@github.com:acme/analytics.git",
"branch": "main",
"git_auth_method": "ssh",
"sqlmesh_environment": "prod",
"sqlmesh_version": "0.130.0",
"use_managed_state_database": true,
"auto_apply": false,
"run_tests": true,
"deployed": true,
"suspended": false,
"status": "active",
"commits_behind": 0,
"current_commit_sha": "a1b2c3d",
"latest_commit_sha": "a1b2c3d",
"latest_commit_message": "Add orders model",
"cpu_request": "500m",
"cpu_limit": "2000m",
"memory_request": "1Gi",
"memory_limit": "4Gi",
"concurrency_policy": "Allow",
"successful_runs_history_limit": 3,
"failed_runs_history_limit": 3,
"created_at": "2026-01-15T10:00:00Z",
"updated_at": "2026-02-20T14:30:00Z"
}
],
"total": 3
}
GET /api/v1/projects/:id
Returns a single project by ID.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | Project ID |
Response
Returns a single project object (same shape as list items above).
POST /api/v1/projects
Creates a new project and auto-deploys it. For SQLMesh projects, dagctl reads the repository to detect gateway names from your config.yaml or config.py.
Request Body
SQLMesh project:
{
"name": "analytics",
"description": "Core analytics models",
"project_type": "sqlmesh",
"repository_url": "https://github.com/acme/analytics",
"branch": "main",
"git_auth_method": "github_app",
"sqlmesh_environment": "prod",
"sqlmesh_version": "0.130.0",
"use_managed_state_database": true,
"auto_apply": false,
"run_tests": true
}
dbt project:
{
"name": "dbt-core",
"project_type": "dbt",
"repository_url": "https://github.com/acme/dbt-project",
"branch": "main",
"git_auth_method": "github_app",
"dbt_version": "1.8.0",
"python_version": "3.11",
"polling_interval": "5m",
"version_strategy": "semantic"
}
Body Fields
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Project name |
project_type |
string | no | "sqlmesh" (default) or "dbt" |
repository_url |
string | yes | Git repository URL |
branch |
string | no | Branch name (default: "main") |
git_auth_method |
string | no | "none", "ssh", or "github_app" |
git_secret_ref |
string | no | Name of the SSH key secret (when git_auth_method is "ssh") |
git_path |
string | no | Subdirectory within the repo containing the project |
description |
string | no | Human-readable description |
sqlmesh_environment |
string | no | SQLMesh environment name (default: "prod") |
sqlmesh_version |
string | no | SQLMesh version (must be a supported version) |
use_managed_state_database |
boolean | no | Use dagctl-managed state DB (default: true for SQLMesh) |
auto_apply |
boolean | no | Automatically apply plans without approval |
run_tests |
boolean | no | Run tests during execution |
cpu_request |
string | no | Kubernetes CPU request (default: "500m") |
cpu_limit |
string | no | Kubernetes CPU limit (default: "2000m") |
memory_request |
string | no | Kubernetes memory request (default: "1Gi") |
memory_limit |
string | no | Kubernetes memory limit (default: "4Gi") |
concurrency_policy |
string | no | Kubernetes CronJob concurrency policy: "Allow", "Forbid", "Replace" (default: "Allow") |
suspended |
boolean | no | Start the project in suspended state |
agent_context |
string | no | Custom context for the AI agent (max 10,000 characters) |
dbt_version |
string | no | dbt-core version (dbt projects only) |
python_version |
string | no | Python version for dbt build (dbt projects only) |
polling_interval |
string | no | Version polling interval, e.g. "5m", "30s" (dbt projects only, minimum 10s) |
version_strategy |
string | no | "semantic" or "continuous" (dbt projects only) |
Response
Returns 201 Created with the project object.
PUT /api/v1/projects/:id
Updates an existing project. Only supplied fields are changed. If the project is deployed, the ArgoCD Application is updated automatically.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | Project ID |
Request Body
All fields are optional. Same fields as create, with these additions:
| Field | Type | Description |
|---|---|---|
auto_apply |
boolean | Automatically apply plans without approval |
run_tests |
boolean | Run tests during execution |
suspended |
boolean | Suspend or resume the project |
remediation_auto_merge |
boolean | Automatically merge remediation PRs |
max_concurrent_job_runs |
integer | Maximum concurrent job runs |
status |
string | Override project status |
Response
Returns 200 OK with the updated project object.
DELETE /api/v1/projects/:id
Deletes a project. If the project is deployed, it is undeployed first via ArgoCD. The managed state database is also deleted if use_managed_state_database is true.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id |
string | Project ID |
Response
POST /api/v1/projects/:id/deploy
Deploys a project by creating or updating its ArgoCD Application.
Response
DELETE /api/v1/projects/:id/deploy
Undeploys a project by removing its ArgoCD Application. The project record is retained.
Response
POST /api/v1/projects/:id/run
Triggers an immediate run using the project's default job configuration. If no job exists for the project, a default one is auto-created. This is the "Run Now" shortcut that does not require a pre-existing job ID.
Response
{
"job_run_id": "run_abc123",
"job_name": "analytics-scheduled-run-manual-20260428-120000",
"status": "pending",
"message": "Run triggered successfully"
}
GET /api/v1/projects/:id/sync-status
Returns the current git sync status for the project.