Public API
Anything you can do in the app, you can do with the public API, apart from the few things listed under What stays in the app.
Use the public API to put run status on a dashboard, check a workflow in CI, sync workflows from another system or start runs from your own scheduler.
The base URL is https://api.dagweave.com. Every endpoint is under /api/v1
and needs an API token.
Endpoints
Section titled “Endpoints”Every POST, PUT, PATCH and DELETE needs an
Idempotency-Key header, except the ones that change
nothing: validate, decompile, the two expression checks and the cluster listing.
Each endpoint has the same permission and plan checks as the matching action in the UI. A personal token can’t do more than the person who made it. A team token acts as an Admin of its team, narrowed by its scopes.
Authentication
Section titled “Authentication”curl -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ https://api.dagweave.com/api/v1/runsNo Authorization header gets 401 unauthorized. An unknown, expired or
revoked token gets 401 invalid or revoked API token.
Scopes
Section titled “Scopes”Each endpoint needs exactly one scope. No scope includes another, and there’s no wildcard.
| Scope | Allows |
|---|---|
runs:read |
Listing runs and reading a single run, adopted runs, run diffs and metrics. |
runs:logs |
Reading a step’s log output. |
runs:artifacts |
Listing a run’s artifacts with download links, and reading an artifact’s content. |
runs:write |
Starting, rerunning, stopping, terminating, suspending, resuming, retrying and cancelling a run, uploading its input files, sharing a run from your own machine, deploying a schedule and listing where a workflow can run. |
workflows:read |
Listing and reading workflows, reading step types, checking a draft and the builder helpers. |
workflows:write |
Creating, updating and duplicating workflows, moving their steps to newer WorkflowTemplate versions, setting their labels and a template’s resources, and importing. |
workflows:delete |
Deleting a workflow. |
git:read |
Reading the GitHub App’s status, the repos it reaches and a workflow’s Git link. |
git:write |
Linking and unlinking Git files, syncing a link and Push to Git. |
templates:read |
Listing and reading WorkflowTemplates and marketplace listings. |
templates:write |
Publishing WorkflowTemplates, publishing or unpublishing a version, installing from the marketplace and splitting a workflow into WorkflowTemplates. |
triggers:read |
Listing triggers. |
triggers:write |
Creating, updating and deleting triggers. |
clusters:read |
Listing connectors and machines, reading a connector’s logs, listing data sources and their items, and listing what a cluster has to import. |
clusters:write |
Removing a connector or a machine, and adding or removing a data source. |
team:read |
Reading teams, members, invites, groups, alerts, SSO, plans, usage, sharing, dispatch scopes and run identities. |
team:write |
Changing all of those. |
audit:read |
Reading the audit log. |
A missing scope gets 403. The message names the scope and the label it has on
the token screen:
this token doesn't have the runs:logs scope ("Read step logs"), which this endpoint needs. Add it under API tokens, Edit scopes, and the same token works hereChange the token’s scopes and call again. The token keeps its value. A token that GitHub Actions got from a trust rule is told instead that a team owner has to trust the repository with that scope.
A token with only runs:write can start runs but not read them, and one with
only runs:read can’t read logs. Add both when you need both.
Scopes only narrow your role. A Viewer’s token can’t start a run, even with
runs:write. An Editor’s token with team:write still can’t change what only an
Owner or Admin can change in the app. audit:read gets 402 if your plan
doesn’t include the audit log.
GET /api/v1/runs
Section titled “GET /api/v1/runs”Your team’s runs as a JSON array, newest first.
| Parameter | Description |
|---|---|
limit |
Page size. Defaults to 50, maximum 200. |
offset |
Number of runs to skip. |
includeTest |
true to include runs started from the builder’s test panel. They’re left out by default. |
phase |
Only runs in this phase. failed matches every kind of failure, and running matches pending runs too. |
connectorId |
Only runs that went to this cluster or machine. |
since |
Only runs created at or after this RFC 3339 timestamp. A bad one gets 400. |
| Field | Description |
|---|---|
id, workflowId, workflowName |
The run and its workflow. |
connectorId |
The cluster connector the run went to. |
triggerId, source |
What started it, such as manual, cron, webhook or test. |
actorId, actorEmail |
Who started it. Absent for scheduled and webhook runs, and actorEmail is absent if the account no longer exists. |
phase, message |
Current state. |
rootCauseNode, rootCauseMessage |
On a failed run, the step that caused the failure. |
createdAt, startedAt, finishedAt |
startedAt and finishedAt are null until the run gets that far. |
argoNamespace, argoName |
Where the run lives on the cluster. |
Other optional fields are left out when empty. Adopted runs never appear here.
GET /api/v1/runs/{id}
Section titled “GET /api/v1/runs/{id}”One run in full. A run that doesn’t exist or belongs to another team gets
404. So does an adopted run, unless you administer the team’s clusters or have
access to that cluster.
Top-level fields: id, workflowId, workflowName, connectorId,
connectorName, triggerId, source, actorEmail, phase, message,
progress, createdAt, startedAt, finishedAt, argoNamespace, argoName
and params. workflowName is absent once the workflow is deleted. trigger
is the trigger that started the run, in the shape
GET /api/v1/triggers returns, while it exists.
nodes has one entry per step:
| Field | Description |
|---|---|
id, name, phase, message |
The step and its state. |
startedAt, finishedAt |
When Argo created and finished the step. |
containerStartedAt |
When the container started. The gap after startedAt is time spent queued. |
exitCode |
The container’s exit code, when there was a container. |
resources |
requests and limits, each with cpu and memory as Kubernetes quantities such as 100m and 128Mi, if the step set them. peak is the most the step used of each, and usage the last sample. A connector older than 0.14.0 sends only usage. |
recommendation |
On a finished run, a new size for the step’s template from recent runs’ peaks: requests or limits, the basis (peak, runs, headroomPct), and target, where one click would land it. No target means Dagweave has no copy of the template it can edit. See Right-size a step. |
wait |
Why a pending step hasn’t started: kind is mutex, semaphore or unschedulable. |
segments |
On a traced cluster, where the step’s time went, in milliseconds: podCreationMs, artifactLoadMs, artifactSaveMs, logSaveMs. |
artifacts has name, bucket, key and url for each output artifact.
logs has nodeId and location for each step log. The location is in your
own storage, so log contents never pass through Dagweave.
triggeredBy has kind (user, api-token, trigger or system), id,
name, and email when a person started it. annotations holds every
annotation Dagweave put on the run’s Workflow, yours and the dagweave.com/
ones from Know who started a run.
Neither appears on an adopted run.
outputs holds the run’s output parameters once there are any: parameters for
the workflow’s own, and nodes for each step’s, with nodeId, nodeName and
parameters. Each parameter has name and value. truncated means the value
was over 4 KB and was cut. redacted means it looked like a credential and was
never sent to Dagweave.
adopted, queueWait (its place in the run queue), placement
(why it landed on that cluster) and tracing links appear when they apply.
GET /api/v1/runs/{id}/nodes/{nodeId}/logs
Section titled “GET /api/v1/runs/{id}/nodes/{nodeId}/logs”One step’s log output. The step id comes from the run’s nodes, which needs
runs:read, so you’ll usually want both scopes.
| Parameter | Description |
|---|---|
tail |
Number of lines from the end. Defaults to 200, maximum 5000. |
since |
How far back to read, as a Go duration such as 30m or 2h. Maximum 720h. An invalid value is ignored. |
containers |
all to include every container in the step’s pod. By default you get only the step’s main container. |
The response has kind and nodeId, plus:
kind |
Meaning |
|---|---|
pointer |
location is the log object in your storage. Dagweave doesn’t hold your storage credentials, so fetch it yourself. |
content |
content holds the log lines, from Dagweave’s log storage. |
collecting |
Logs are expected but haven’t arrived. Try again in a few seconds. |
expired |
Older than your team keeps logs for, or removed when its log storage filled up. See message. |
none |
No logs for this step. See message. |
A run or step that doesn’t exist or isn’t yours gets 404. A log backend
failure gets 502.
GET /api/v1/runs/{id}/artifacts
Section titled “GET /api/v1/runs/{id}/artifacts”A run’s artifacts as a JSON array, like the table in the run view.
Each has name, bucket, key and url, plus downloadUrl and
downloadExpiresAt when Dagweave can give you a link. The link opens the file
for 15 minutes, and each one goes in the audit log.
There’s no downloadUrl when the run’s connector is too old to send artifacts
back.
GET /api/v1/runs/{id}/artifacts/content
Section titled “GET /api/v1/runs/{id}/artifacts/content”Reads one artifact through the connector, like View in the app. Pass the
bucket and key from the list as query parameters.
curl -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ "https://api.dagweave.com/api/v1/runs/run-8f21/artifacts/content?bucket=artifacts&key=run-8f21/report.csv"The response is JSON with bucket, key, size, encoding and content.
Text comes back as it is, with encoding set to utf-8. Anything else is
base64, with encoding set to base64.
| Status | Meaning |
|---|---|
404 |
The run doesn’t exist or isn’t yours, or it didn’t write that artifact. |
413 |
The file is over 20 MiB. Use its downloadUrl instead. |
502 |
The connector couldn’t read the file. |
503 |
The run’s connector needs upgrading before it can send artifacts back. |
Adopted runs, diffs and metrics
Section titled “Adopted runs, diffs and metrics”| Endpoint | Returns |
|---|---|
GET /api/v1/runs/adopted |
Runs Dagweave didn’t start, newest first: ones submitted straight to Argo on your clusters, and ones you started with dagweave run on your own machine, which carry a local field naming the machine. Takes limit, offset, phase, connectorId and since, as GET /api/v1/runs does. See Adopted runs. |
GET /api/v1/runs/{id}/diff |
What changed since the previous run of the same workflow: parameters, images, resources, pod spec, target and definition. |
GET /api/v1/metrics |
Success rate, run counts and durations across your workflows. |
GET /api/v1/metrics/workflows |
One health row per workflow, as on the Runs page. |
GET /api/v1/workflows/{id}/metrics |
The same numbers for one workflow. |
The three metrics endpoints take days, which defaults to 30.
POST /api/v1/workflows/{id}/run
Section titled “POST /api/v1/workflows/{id}/run”Starts a run of a saved workflow and returns its id. You can’t undo it.
curl -X POST https://api.dagweave.com/api/v1/workflows/wf-04c9/run \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"connectorId":"con-1a77","namespace":"argo"}'| Field | Required | Description |
|---|---|---|
connectorId |
Yes | The connector to send the run to, or one of your machines. |
namespace |
Yes | The Kubernetes namespace on that connector’s cluster. argo for a machine. |
argoInstanceId |
No | Which Argo instance to use, when the connector serves more than one. local for a machine. |
params |
No | An object of string values that override the workflow’s parameters for this run. |
annotations |
No | An object of string values written onto the run’s Workflow as Kubernetes annotations. At most 20, each value at most 1024 bytes. Keys under dagweave.com/, dagweave.io/, kubernetes.io/, k8s.io/ and argoproj.io/ return 400. See Know who started a run. |
inputArtifacts |
No | Files for the workflow’s input artifacts, sent inline. Artifact name to {"filename": "...", "content": "<base64>"}, or just the base64 string. The whole body still has to fit in 1 MiB. |
inputHandles |
No | Bigger files you uploaded first with POST /api/v1/workflows/{id}/inputs. Artifact name to the handle it returned. |
Any other field gets 400. You can’t start a test run through the API.
Success is 200:
{"runId": "run-8f21"}Follow it with GET /api/v1/runs/{id}.
On top of the general errors:
400: the connector isn’t enrolled, or a parameter with no default got no value inparams. The message says which.402: your plan doesn’t include running workflows. The message names the cheapest plan that does.403: dispatch scoping doesn’t let you run workflows in that namespace.404: the workflow or connector doesn’t exist.409: the run needs its own namespace and the cluster’s Argo controller only watches fixed namespaces.429withoutRetry-After: you’ve used your plan’s monthly executions.502: the cluster refused the run.503: the connector is offline. Nothing started, so retry with the sameIdempotency-Keyonce it’s back.
POST /api/v1/runs/{id}/rerun
Section titled “POST /api/v1/runs/{id}/rerun”Starts a new run with the same connector, namespace, Argo instance, parameters, input files and annotations as the run you name. It uses the workflow as saved now, including any edits since.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/rerun \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. To change the target or parameters, use
POST /api/v1/workflows/{id}/run.
Success is 200 with {"runId": "..."}, recorded as a manual run by the
token’s owner.
404: the run doesn’t exist or isn’t yours.400: it’s a test run. Rerun it from the builder.409: its input files were read straight from the cluster, so Dagweave has no copy.
Other errors match starting a run.
POST /api/v1/runs/{id}/stop
Section titled “POST /api/v1/runs/{id}/stop”Stops a running run, like Stop run in the run view. Running steps stop, exit handlers still run and the run ends as failed.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/stop \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204 once the cluster confirms, or:
| Status | Meaning |
|---|---|
403 |
You can see the run but aren’t allowed to run its workflow. |
404 |
The run doesn’t exist or isn’t yours. |
409 |
The run isn’t pending or running, hasn’t reached its cluster, or is an adopted run. |
502 |
The cluster refused the stop. |
503 |
The connector is offline. The stop is refused, not queued. |
504 |
No confirmation within 20 seconds. The run may still be going, so check it before you retry. |
To drop a run that’s still in the queue, use
POST /api/v1/runs/{id}/cancel.
POST /api/v1/runs/{id}/terminate
Section titled “POST /api/v1/runs/{id}/terminate”Terminates a running run, like Terminate run in the run view. Unlike stop, the run ends at once and its exit handlers don’t run.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/terminate \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204 once the cluster confirms. The errors are the stop
errors.
POST /api/v1/runs/{id}/suspend
Section titled “POST /api/v1/runs/{id}/suspend”Suspends a running run, like Suspend run in the run view. Steps already running finish and no new ones start.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/suspend \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204 once the cluster confirms. The errors are the stop
errors, and 409 also means a stop or terminate was already sent for the run.
POST /api/v1/runs/{id}/resume
Section titled “POST /api/v1/runs/{id}/resume”Resumes a suspended run, like Resume run in the run view. It clears the run’s suspend and lets every suspend step that is waiting go.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/resume \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204 once the cluster confirms. The errors are the stop
errors, and 409 also means the connector is older than 0.16.0.
POST /api/v1/runs/{id}/retry
Section titled “POST /api/v1/runs/{id}/retry”Retries a failed run, like Retry run in the run view. The same run goes on
from its failed steps, and steps that succeeded are kept. To start a new run
instead, use POST /api/v1/runs/{id}/rerun.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/retry \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204 once the cluster confirms. The errors are the stop
errors, except that the run must be failed or errored. 409 also means the
connector is older than 0.16.0.
POST /api/v1/runs/{id}/cancel
Section titled “POST /api/v1/runs/{id}/cancel”Cancels a queued run, like Cancel run in the run view. The run is removed and never reaches a cluster.
curl -X POST https://api.dagweave.com/api/v1/runs/run-8f21/cancel \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"No body. Returns 204, or 404 if the run doesn’t exist or isn’t yours, or 409
if it has already gone to its cluster. Stop that one instead.
POST /api/v1/workflows/{id}/inputs
Section titled “POST /api/v1/workflows/{id}/inputs”Puts one file for a run into your cluster’s own object store before the run starts, like attaching a file in the Run dialog. Use it for a file too big to send inline. Dagweave doesn’t keep a copy.
Send JSON with the file in base64, or a multipart form with a file part, as the
app does.
| Field | Required | Description |
|---|---|---|
connectorId, namespace |
Yes | Where the run will go. The run has to use the same connector. |
argoInstanceId |
No | When the connector serves more than one. |
artifact |
Yes | The workflow’s input artifact this file is for. |
filename |
No | Defaults to the artifact’s name. |
content |
Yes | The file, base64. Up to 3 MiB before encoding. |
Success is 200 with handle, filename and expiresAt. The handle lasts an
hour. Pass it in inputHandles when you start the run.
The checks match starting a run, and they run before the file moves. An offline connector or a namespace you can’t use is refused here, and so is an artifact the workflow doesn’t declare.
POST and DELETE /api/v1/runs/{id}/share
Section titled “POST and DELETE /api/v1/runs/{id}/share”Shares a run from your own machine running Dagweave Local with your
team, or stops sharing it. No body. A run you started with dagweave run is in
GET /api/v1/runs/adopted. One you sent to the
machine from Dagweave is in GET /api/v1/runs.
POST /api/v1/workflows/{id}/deploy-schedule
Section titled “POST /api/v1/workflows/{id}/deploy-schedule”Puts a CronWorkflow on a cluster, with the WorkflowTemplates it uses. From then
on the cluster starts runs on its schedule, so this needs runs:write. See
Deploy a CronWorkflow instead.
{"connectorId": "con-1a77", "namespace": "argo"}Add argoInstanceId when the connector serves more than one. Success is 200
with {"status": "deployed"}. A workflow linked to Git gets 409, because your
GitOps tool deploys it. A schedule that would run more often than your plan
allows gets 429, and the error says so.
GET /api/v1/workflows/{id}/deploy-schedule
Section titled “GET /api/v1/workflows/{id}/deploy-schedule”Where the workflow’s CronWorkflow is deployed, as {"schedules": [...]}. Each
entry has connectorId, connectorName, argoInstanceId, namespace, name
(the CronWorkflow’s name on the cluster), schedules, runsPerMonth and
installedAt. Needs runs:read.
DELETE /api/v1/workflows/{id}/deploy-schedule
Section titled “DELETE /api/v1/workflows/{id}/deploy-schedule”Deletes the CronWorkflow from its cluster, so it stops starting runs and stops
counting against your plan. Needs runs:write. With no body it’s removed from
everywhere it’s deployed. To remove one, send
{"namespace": "argo", "argoInstanceId": "..."}.
Success is 200 with the same list, each entry carrying an outcome: removed
when the cluster confirmed it, queued when the connector is offline and will
delete it when it reconnects, or unreachable when the connector has been
deleted and you need to delete the CronWorkflow yourself. A workflow that isn’t
deployed there gets 404. A cluster that refuses gets 502, and one that doesn’t
answer gets 503; in both cases the schedule is still deployed and still counted.
Workflows
Section titled “Workflows”GET /api/v1/workflows
Section titled “GET /api/v1/workflows”Your team’s workflows as a JSON array. Each has id, name and version, plus
folder, namespace and labels when set. A workflow with no name is listed
under its generateName, without the trailing dash. Dagweave’s examples are included with
"readOnly": true.
| Parameter | Description |
|---|---|
q |
Case-insensitive match on part of the name. |
label, namespace, folder |
Exact match. |
limit, offset |
Page through the results. Leave both out to get everything. |
Filters apply before paging. X-Total-Count gives the number of matches.
GET /api/v1/workflows/{id}
Section titled “GET /api/v1/workflows/{id}”The workflow as Dagweave IR JSON, the same document the builder loads. 404 if
it doesn’t exist or belongs to another team.
The ETag header holds the workflow’s version. You need it to
update the workflow.
GET /api/v1/workflows/{id}/runs
Section titled “GET /api/v1/workflows/{id}/runs”One workflow’s runs, newest first. Each row matches GET /api/v1/runs.
| Parameter | Description |
|---|---|
phase |
Only runs in this phase. failed matches every kind of failure, and running matches pending runs too. |
since |
Only runs created at or after this RFC 3339 timestamp. |
includeTest |
true to include test runs. |
limit, offset |
Page size, default 50 and maximum 200, and runs to skip. |
A bad since gets 400. A workflow that doesn’t exist or isn’t yours gets 404.
GET /api/v1/workflows/{id}/clusters
Section titled “GET /api/v1/workflows/{id}/clusters”Where a workflow can run, as {"clusters": [...], "machines": [...]}. It needs
runs:write.
clusters is ranked like the Run dialog. Each entry has connectorId,
connectorName, argoInstanceId, namespace and available, plus reason
when it isn’t available and rank when it’s ranked.
machines lists your own machines running Dagweave Local. Each
has connectorId, name, status, and the namespace (argo) and
argoInstanceId (local) a run on it names. Nobody else can send a run to your
machine, so nobody else sees it here. A machine takes the run only while
dagweave listen is running on it.
GET /api/v1/node-types
Section titled “GET /api/v1/node-types”The step types an IR document can use. Read it before you write IR.
| Parameter | Description |
|---|---|
typeId |
Return only this type, with its config schema. |
A JSON array sorted by typeId, one entry if you passed typeId:
| Field | Description |
|---|---|
typeId |
The value a step’s typeId must have. |
label, description |
Human-readable name and summary. |
version |
The value a step’s nodeVersion quotes to pin this type. |
core |
false marks a type that reaches past the workflow itself: Resource, ContainerSet and Plugin. Every plan can use every type. |
podBased |
false means the step doesn’t get its own pod, so pod settings such as resources have no effect. |
paletteHidden |
true for types that keep imported Argo manifests in their exact shape. New workflows usually want the regular equivalent. See Import-only types. |
ports |
inputs and outputs, each a list of ports with a name and a type of parameter or artifact. |
configSchema |
Only when you pass typeId. The JSON Schema for the step’s config. |
An unknown typeId gets 404 with every valid id in the message. The list is
the same for every team. Catalog items aren’t step types and don’t
appear.
POST /api/v1/workflows/validate
Section titled “POST /api/v1/workflows/validate”Checks a draft. Nothing is saved or run, so call it as often as you like.
{"workflow": "apiVersion: argoproj.io/v1alpha1\nkind: Workflow\n..."}Send the whole document as one string: Argo YAML (Workflow,
WorkflowTemplate, ClusterWorkflowTemplate or CronWorkflow) or Dagweave IR
JSON. Dagweave detects which. An empty workflow or any other field gets 400.
A draft with problems still gets 200:
{ "valid": false, "format": "argo-yaml", "faults": [ { "severity": "error", "rule": "template-not-found", "path": "spec.templates[0].dag.tasks[1].template", "message": "spec.templates[0].dag.tasks[1].template names template \"trasnform\", which this workflow does not define. This workflow defines: main, extract." } ], "manifest": "apiVersion: argoproj.io/v1alpha1\nkind: Workflow\n..."}| Field | Description |
|---|---|
valid |
false if any fault has severity error. A warning won’t stop the workflow running. |
format |
How Dagweave read your input: argo-yaml or dagweave-ir. |
faults[].rule |
One of parse, schema, unknown-field, entrypoint-unset, template-not-found, task-not-found, unused-parameter, import, compile, not-runnable, not-accepted or plan. |
faults[].path |
Where the fault is. A dotted path for YAML, a JSON pointer for IR. Absent when the fault applies to the whole document. |
manifest |
The Argo manifest your draft compiles to. Absent if it didn’t compile. |
not-accepted means the cluster would reject the compiled manifest. Template
names in its message refer to manifest, not your draft.
plan means your plan won’t let you save that step because it uses a catalog
WorkflowTemplate outside the free ones. It’s the same check a
save runs, so a draft with no plan faults won’t be refused for its steps. The
message names the step and the cheapest plan that allows it. For IR the path
points at the step; for YAML look for the step’s name.
POST /api/v1/workflows
Section titled “POST /api/v1/workflows”Saves a new workflow and returns its id and version. It doesn’t start a run.
curl -X POST https://api.dagweave.com/api/v1/workflows \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"workflow":"apiVersion: argoproj.io/v1alpha1\nkind: Workflow\nmetadata:\n generateName: hello-\nspec:\n entrypoint: main\n templates:\n - name: main\n container:\n image: alpine:3.19\n command: [echo, hi]\n"}'The body is one workflow field, in either format the
draft check takes. An empty workflow, a
baseVersion or any other field gets 400.
Success is 200:
{"id": "wf-04c9", "version": "9f86d081884c7d65...2b0061"}version is 64 hex characters, shortened here. Keep it for your next update.
If the draft check finds an error, you get 422 with the check’s response as
the body and nothing is saved. Warnings don’t block a save. Workflows are stored
as IR, so YAML you save reads back as IR.
Builder limits apply too:
400: a catalog reference doesn’t resolve.402: the workflow uses a catalog WorkflowTemplate your plan doesn’t include. The message names the steps and the cheapest plan that allows them, and the draft check reports the same steps asplanfaults.403with"code": "email_unverified": your email isn’t verified and the save goes past one workflow with up to ten steps.429withoutRetry-After: you’ve hit your plan’s workflow limit.
PUT /api/v1/workflows/{id}
Section titled “PUT /api/v1/workflows/{id}”Replaces a saved workflow and returns the new version.
curl -X PUT https://api.dagweave.com/api/v1/workflows/wf-04c9 \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"workflow":"apiVersion: argoproj.io/v1alpha1\nkind: Workflow\nmetadata:\n generateName: hello-\nspec:\n entrypoint: main\n templates:\n - name: main\n container:\n image: alpine:3.19\n command: [echo, goodbye]\n","baseVersion":"9f86d081884c7d65...2b0061"}'Anything you leave out of the document is removed.
baseVersion is required. Use the version from your last save, a read or the
list. If someone saved since, you get 409 with the current version in the
message, and nothing changes. Read it again, reapply your edit and retry. An
If-Match header with the version is checked too.
If someone has the workflow open in Dagweave while you update it, nothing gets overwritten. They’ll be asked whether to reload or keep their changes.
Success is 200 with {"id": "...", "version": "..."}. The checks match a
create, and a 422 leaves the stored workflow alone.
404 if the workflow doesn’t exist, belongs to another team or is a Dagweave
example. To change an example, duplicate it.
PUT /api/v1/workflows/{id}/labels
Section titled “PUT /api/v1/workflows/{id}/labels”Replaces a workflow’s labels.
curl -X PUT https://api.dagweave.com/api/v1/workflows/wf-04c9/labels \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"labels":["prod","etl"]}'Send the full set. Labels you leave out are removed, and {"labels": []} clears
them. Dagweave trims, de-duplicates and sorts them. {} or any other field gets
400.
Success is 200 with an empty body. The workflow’s version doesn’t change.
404 works as for an update.
POST /api/v1/workflows/{id}/duplicate
Section titled “POST /api/v1/workflows/{id}/duplicate”Copies a workflow into a new one with “ copy” on the end of its name. No body.
Success is 200 with the new id. It counts towards your plan’s workflow limit
like any other create.
POST /api/v1/workflows/{id}/upgrade
Section titled “POST /api/v1/workflows/{id}/upgrade”Moves every step that calls an older version of one of your team’s
WorkflowTemplates to its newest published version, like Update N workflows in
the WorkflowTemplates view. Send {"base": "..."} to move only one
WorkflowTemplate, or no body for all of them. A step’s nodeVersion is left
alone. Success is 200 with {"upgraded": 3}, the number of steps that changed.
A workflow linked to Git gets 409.
POST /api/v1/workflows/{id}/resources
Section titled “POST /api/v1/workflows/{id}/resources”Sets one template’s CPU and memory requests or limits, like the button on a step in the run view. Send the template’s name, the new values and the version you’re changing:
{"template": "train", "requests": {"memory": "192Mi"}, "baseVersion": "9f86d081884c7d65...2b0061"}A finished run’s steps carry these in recommendation from
GET /api/v1/runs/{id}: the values in requests and
limits, and the workflow, template and version to use under target. Only the
keys you send change.
Success is 200 with an outcome: saved with the new version,
pull-request with its url for a workflow linked to Git, or unchanged when
the workflow already asks for all of it. A pull request also needs git:write. A
stale baseVersion gets 409, and a template no step of the workflow runs gets
400.
DELETE /api/v1/workflows/{id}
Section titled “DELETE /api/v1/workflows/{id}”Deletes a workflow. Needs workflows:delete, which workflows:write doesn’t
include.
curl -X DELETE https://api.dagweave.com/api/v1/workflows/wf-04c9 \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"Success is 204, and a retry with the same Idempotency-Key gets 204 with
Idempotency-Replayed: true. 404 works as for an update.
What does not come back
Section titled “What does not come back”You can’t undo a delete. The id stops working and past runs no longer point at a workflow.
Dagweave also deletes WorkflowTemplates it installed for the workflow once nothing else uses them. Deleting the last workflow that uses a catalog WorkflowTemplate uninstalls it. A WorkflowTemplate stays if:
- another of your workflows references it
- a run is in progress in that cluster and namespace
- it’s a ClusterWorkflowTemplate
- it’s a building block you vetted yourself
This cleanup runs after the delete. If it fails, the unused WorkflowTemplate stays on the cluster.
Builder helpers
Section titled “Builder helpers”What the builder asks the server while you edit. None of it saves anything, and
all of it needs workflows:read.
| Endpoint | Does |
|---|---|
POST /api/v1/decompile |
Turns an Argo manifest into Dagweave IR, like opening YAML on the canvas. Send {"workflow": "..."}. |
GET /api/v1/ir-schema |
The JSON Schema for Dagweave IR. |
GET /api/v1/blueprints |
The starter workflows in the Library, each with its IR. |
GET /api/v1/catalog |
The catalog items a workflow can use as steps. |
POST /api/v1/expressions/check |
Checks a when, withParam or depends field the way the builder does. Send kind, text and optionally scope. |
POST /api/v1/expressions/evaluate |
Runs an expression against sample values, like Try it. Send what the check takes plus sample. Needs a plan with the expression builder. |
GET /api/v1/expressions/vocabulary |
The functions and words an expression can use. |
GET /api/v1/schedule-preview |
The next three times a cron schedule fires. Pass spec, and tz for a time zone other than UTC. |
See Expressions for what the checks look at.
Import
Section titled “Import”Each import makes new workflows, so it needs workflows:write. The reply has
imported, the number of workflows made, and results, one entry per manifest
with name, status and, where they apply, id, error and fidelity.
status is imported, failed, blocked or skipped. blocked means you hit
your plan’s workflow limit, and everything after it is skipped.
POST /api/v1/import/bulk
Section titled “POST /api/v1/import/bulk”The paste box in Import. Send {"yaml": "..."} with one or more Argo
manifests separated by ---.
POST /api/v1/git/import
Section titled “POST /api/v1/git/import”Copies every Argo manifest in a GitHub repo, or under one path in it, into new
workflows. Send repo as owner/name, plus branch and path if you need
them. It’s a one-off copy. To keep workflows following the repo,
link it instead.
403 means the GitHub App can’t see the repo. 404 means it isn’t installed
there.
POST /api/v1/cluster/list
Section titled “POST /api/v1/cluster/list”Lists the WorkflowTemplates and CronWorkflows in one namespace of a connected
cluster, so you can pick what to import. Send connectorId and namespace, and
argoInstanceId when the connector serves more than one. It changes nothing, so
it takes clusters:read and no Idempotency-Key.
The reply has items, each with kind, name, namespace and fidelity, and
truncated when there were too many to list.
POST /api/v1/cluster/import
Section titled “POST /api/v1/cluster/import”Imports the definitions you name from that namespace. Send what the list takes
plus names, an array of names from its items.
These go through your team’s GitHub App. A linked workflow follows its file in Git and can’t be edited in Dagweave. See WorkflowTemplates from Git.
GET /api/v1/git/status
Section titled “GET /api/v1/git/status”Whether the GitHub App is set up here, as configured, and which GitHub accounts
your team has connected, as accounts.
GET /api/v1/git/repos
Section titled “GET /api/v1/git/repos”The repos the GitHub App can reach, as repos, each with owner, name,
fullName and defaultBranch. unreachable lists any connected account
Dagweave couldn’t read.
POST /api/v1/git/link
Section titled “POST /api/v1/git/link”Links a file, or every Argo file in a folder, as new workflows. Send repo,
ref (the branch) and path. An empty path links the whole repo. Linking
again re-reads what’s already linked.
The reply has the same shape as an import.
/api/v1/workflows/{id}/git
Section titled “/api/v1/workflows/{id}/git”| Method | Scope | Does |
|---|---|---|
GET |
git:read |
Returns the link: repo, ref, path, sha, contentHash, name, kind, state and syncedAt. state is ok, missing or unreadable. 404 if the workflow isn’t linked. |
PUT |
git:write |
Links an existing workflow to one file. Send repo, ref and path. The workflow’s body is replaced with the file’s. |
DELETE |
git:write |
Unlinks it. It stays as an ordinary workflow you can edit. Returns 204. |
POST /api/v1/workflows/{id}/git/sync re-reads the file at the tip of its
branch now and returns the link. It needs git:write.
POST /api/v1/workflows/{id}/publish
Section titled “POST /api/v1/workflows/{id}/publish”Writes the workflow’s YAML to a repo as a pull request or a commit, like Push to Git in the app.
| Field | Description |
|---|---|
repo, path, branch |
The repo as owner/name, the file to write and the branch. |
mode |
pr or commit. Defaults to pr. |
decompose |
true to write each WorkflowTemplate it uses as its own file. |
token |
A GitHub token, only when the GitHub App can’t reach the repo. |
workflow |
Linked workflows only. Your edit, in either format. Leave it out to push the stored copy. |
contentHash |
Linked workflows only. The contentHash of the link you edited from. |
overwrite |
Linked workflows only. true opens the pull request even though the file changed since contentHash. Ignored for a commit. |
A linked workflow always goes to its own repo, branch and file. If the file
changed in Git since contentHash, you get 409 and nothing is pushed, unless
it’s a pull request with overwrite. If Dagweave can’t read the file, a push
from the last version it could read replaces it. After a pull request, the link
has pullRequest and pullRequestHash, the file version it was opened against.
Success is 200 with url, the pull request or the commit. 402 if your plan
doesn’t include Push to Git.
WorkflowTemplates
Section titled “WorkflowTemplates”GET /api/v1/templates
Section titled “GET /api/v1/templates”Your team’s published WorkflowTemplates. Each has base, versions and
usedBy, the workflows that reference it. Takes limit and offset.
GET /api/v1/templates/{name}
Section titled “GET /api/v1/templates/{name}”One version, by its name such as build-image-v2: name, kind, body (the
YAML), entrypoint and parameters.
POST /api/v1/templates/publish
Section titled “POST /api/v1/templates/publish”Publish as WorkflowTemplate, for a saved workflow. Send name, workflowId
and visibility, which is private, team, marketplace or organisation
and defaults to private. organisation lists it for every team in your team’s
organisation. Success is 200 with name, base and version. Publishing the
same thing again doesn’t make a new version.
A workflow that doesn’t compile to a WorkflowTemplate gets 400, and so does
organisation from a team that isn’t in one. The old marketplace-deployment
visibility is gone and gets 400; send marketplace instead. A marketplace
or organisation listing needs a plan with marketplace publishing, or you get
402.
PUT /api/v1/templates/{name}/published
Section titled “PUT /api/v1/templates/{name}/published”Publishes or unpublishes one version. Send {"published": false} to take it out
of the picker. Success is 200 with an empty body.
Marketplace
Section titled “Marketplace”GET /api/v1/marketplace/listings lists what teams have published to the
marketplace. Your own team’s listings have "own": true.
GET /api/v1/marketplace/listings/{name} returns one listing’s YAML, entrypoint
and parameters, and the team that published it, under the same rule as install: a
listing you can’t see is a 404. POST /api/v1/marketplace/install with
{"name": "..."} copies a listing into your team’s own WorkflowTemplates and
returns name, base and version. All three need a plan with the marketplace.
POST /api/v1/workflows/{id}/decompose
Section titled “POST /api/v1/workflows/{id}/decompose”The Code view’s split. It breaks a saved workflow into a root and a
WorkflowTemplate per reusable step, gives each one a version in your registry and
returns {"yaml": "..."}. No body.
Triggers
Section titled “Triggers”GET /api/v1/triggers
Section titled “GET /api/v1/triggers”Your team’s triggers as a JSON array. Each has id, workflowId,
connectorId, namespace, argoInstanceId, type, enabled, signed,
createdAt and updatedAt, plus workflowName, cronSpec,
concurrencyPolicy, nextFireAt, lastFiredAt, lastRunId, lastError,
gitRepo, gitBranch, gitEvent, paths, pathsIgnore and config when they
apply. A webhook trigger has webhookUrl and an sns or s3 trigger has
snsUrl, the address to send to. Secrets are never returned.
GET /api/v1/workflows/{id}/triggers
Section titled “GET /api/v1/workflows/{id}/triggers”The triggers that run one workflow, in the same shape.
POST /api/v1/triggers
Section titled “POST /api/v1/triggers”Creates a trigger.
curl -X POST https://api.dagweave.com/api/v1/triggers \ -H "Authorization: Bearer $DAGWEAVE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"workflowId":"wf-04c9","connectorId":"con-1a77","namespace":"argo","type":"cron","cronSpec":"0 3 * * *","enabled":true}'| Field | Required | Description |
|---|---|---|
workflowId, connectorId, namespace |
Yes | What it runs and where. |
type |
Yes | manual, cron, github, sns or s3. |
enabled |
No | false by default. |
argoInstanceId |
No | When the connector serves more than one. |
cronSpec, concurrencyPolicy |
cron | A five-field cron expression, and Allow, Forbid or Replace. |
gitRepo, gitBranch, gitEvent, paths, pathsIgnore |
github | As on the Triggers page. |
snsTopicArn, s3Bucket, s3Prefix, s3Suffix |
sns, s3 | As on the Triggers page. |
Success is 200 with the trigger. An sns or s3 trigger adds snsUrl.
A webhook trigger gets 400. Create those in the app, where the secret is shown
to you once.
PUT /api/v1/triggers/{id}
Section titled “PUT /api/v1/triggers/{id}”Edits a trigger. namespace, argoInstanceId, enabled and cronSpec are
replaced, so send each as it should end up. paths, pathsIgnore and
concurrencyPolicy are kept when you leave them out.
Success is 200 with the trigger.
On a webhook trigger, "rotateSecret": true replaces its secret and
"rotateSigningKey": true replaces its signing key, or switches an unsigned
webhook to signed requests. The old credential stops working at once. The reply
carries the new one as secret or signingKey, once: a retry with the same
Idempotency-Key gets the trigger without it, so pass it on straight away. A
signed webhook gets 400 for rotateSecret, and any other trigger type gets
400 for either.
DELETE /api/v1/triggers/{id}
Section titled “DELETE /api/v1/triggers/{id}”Deletes a trigger. Returns 204. Past runs keep its id.
POST /api/v1/triggers/{id}/fire
Section titled “POST /api/v1/triggers/{id}/fire”Starts a run now, like Run now on the Triggers page, on the trigger’s connector
and namespace. Needs runs:write.
{"params": {"env": "staging"}}The body is optional. Success is 200 with {"runId": "..."}. Other errors
match starting a run.
Clusters
Section titled “Clusters”GET /api/v1/connectors
Section titled “GET /api/v1/connectors”Your team’s cluster connectors as a JSON array. Each has id, name, status
(online, offline or pending), connectorVersion, clusterId,
keyFingerprint, servedInstances (each with its Argo instance and namespace),
lastSeenAt, createdAt, disconnected and upgradeCommand.
Machines, connector logs and data sources
Section titled “Machines, connector logs and data sources”| Endpoint | Scope | Does |
|---|---|---|
GET /api/v1/machines |
clusters:read |
The machines running Dagweave Local: yours, or everyone’s if you’re an Owner or Admin. |
GET /api/v1/connectors/{id}/logs |
clusters:read |
The tail of the connector’s own pod logs. Takes tail, default 200. Owners and Admins only. |
GET /api/v1/connectors/{id}/health |
clusters:read |
One connector’s stream counters: sessionSeconds, streamOpens1h, idleCallsPerMinute, streamEndsByReason and the release gate’s verdict in gatePasses and gateReason. Counted per API process. 404 for a connector on another team. |
GET /api/v1/sources |
clusters:read |
Your team’s data sources. |
GET /api/v1/sources/{id}/items |
clusters:read |
A page of a data source’s items, read through its connector. Pass cursor from the last page’s nextCursor. |
GET /api/v1/sources/{id}/items/{itemId} |
clusters:read |
One item with all its fields. |
DELETE /api/v1/connectors/{id} |
clusters:write |
Removes a connector. Runs can’t go to that cluster afterwards. Returns 204. |
DELETE /api/v1/machines/{id} |
clusters:write |
Removes a local machine. Its owner or an Admin can. Returns 204. |
POST /api/v1/sources |
clusters:write |
Registers a data source. Send connectorId, name and type (postgres or s3). The reply has the label to put on the Secret that holds its credentials. |
DELETE /api/v1/sources/{id} |
clusters:write |
Removes a data source. Returns 204. |
To add a connector, use the app. POST /api/v1/connectors gets 400.
Audit log
Section titled “Audit log”GET /api/v1/audit
Section titled “GET /api/v1/audit”Your team’s audit log, newest first. 402 if your plan
doesn’t include it.
| Parameter | Description |
|---|---|
action |
An action name. |
actor |
A user’s email address or id, or a token’s id or name. |
outcome |
The recorded outcome. |
objectType |
Only events about this kind of object, such as workflow, run or api_token. |
objectId |
Only events about the object with this id. Pair it with objectType. |
from, to |
Only events in this time range, as RFC 3339 timestamps. |
before |
Only events before this RFC 3339 timestamp. Use it to page back. |
limit |
Number of events. Defaults to 50, maximum 500. |
format |
csv to download every matching event as a CSV file. limit and before don’t apply to it. |
A timestamp that isn’t RFC 3339 gets 400.
Each event has id, occurredAt, action and outcome, and where they apply
actorEmail, actorIp, actorCredential (session or token),
actorTokenId, actorTokenName, objectType, objectId and details.
Internal user ids are never returned. The CSV drops id and has details as
raw JSON.
GET /api/v1/audit/actions
Section titled “GET /api/v1/audit/actions”The action names in your team’s audit log, to use as the action filter.
The Team settings screens, over the API. Reads need team:read and changes need
team:write. Each route runs the app’s own Owner and Admin checks, so a token
can only change what its owner could change in the app.
| Method | Path | Does |
|---|---|---|
GET |
/api/v1/teams |
Your teams, your role in each and which one the token works in. |
PATCH |
/api/v1/teams/{id} |
Renames a team. Send name. |
GET, POST |
/api/v1/teams/{id}/members |
Lists members, or adds someone who already has an account. Send email and role. |
PATCH, DELETE |
/api/v1/teams/{id}/members/{userId} |
Changes a member’s role, or removes them. |
GET, PUT |
/api/v1/teams/{id}/notifications |
Reads or replaces who gets alerted about failed runs and offline connectors. |
GET, POST |
/api/v1/teams/{id}/invites |
Lists pending invites, or invites someone by email with a role. |
DELETE |
/api/v1/teams/{id}/invites/{inviteId} |
Revokes an invite. |
GET, POST |
/api/v1/teams/{id}/groups |
Lists groups, or creates one. Give idpGroupId and ssoRole to fill it from Google. |
PATCH, DELETE |
/api/v1/teams/{id}/groups/{groupId} |
Renames or deletes a group. |
GET, POST |
/api/v1/teams/{id}/groups/{groupId}/members |
Lists a group’s members, or adds one by userId or a pending invite by inviteId. |
DELETE |
/api/v1/teams/{id}/groups/{groupId}/members/{userId} |
Takes a member out of a group. |
DELETE |
/api/v1/teams/{id}/groups/{groupId}/invites/{inviteId} |
Takes a pending invite out of a group. |
GET, PUT, DELETE |
/api/v1/teams/{id}/sso |
Reads, sets or removes the Google SSO domain. |
PUT |
/api/v1/teams/{id}/sso/enforced |
Turns SSO enforcement on or off. Refused until the domain is proved. |
GET, POST, DELETE |
/api/v1/grants/{type}/{id} |
Who a workflow, connector or template is shared with. Share it or stop sharing it by userId or groupId and relation. |
GET |
/api/v1/dispatch-scopes, /api/v1/dispatch-scoping |
The namespaces runs are limited to, and whether the limit is on. |
PUT |
/api/v1/dispatch-scoping |
Turns the limit on or off with mode: off or enforce. |
POST |
/api/v1/dispatch-scopes/grants |
Lets a member or group run in one namespace. |
DELETE |
/api/v1/dispatch-scopes/{scopeId}/grants |
Takes that away. Send userId or groupId. |
DELETE |
/api/v1/dispatch-scopes/{scopeId} |
Removes a namespace from the list, such as one added with a typo. 409 while anyone holds a grant on it, a run identity names it, or Dagweave manages it. |
POST |
/api/v1/dispatch-scopes/ephemeral |
Has Dagweave make a namespace it owns and cleans up. |
DELETE |
/api/v1/dispatch-scopes/{scopeId}/ephemeral |
Deletes that namespace. |
GET, POST |
/api/v1/sa-specs |
Lists run identities, or drafts one from a template. |
GET |
/api/v1/run-identity-templates |
What each connector allows a run identity to be built from. |
DELETE |
/api/v1/sa-specs/{specId} |
Deletes a draft run identity. |
POST |
/api/v1/sa-specs/{specId}/{action} |
submit, approve, reject, revoke or fork. Send a note if you like. |
GET, PUT |
/api/v1/sa-approval |
Whether new run identities are approved without review. |
GET |
/api/v1/entitlements, /api/v1/plans, /api/v1/usage |
What your plan holds back, every plan on offer, and your log storage: about how much is kept, how far back, and your storage and retention. |
PUT |
/api/v1/usage/retention |
Sets how long your team keeps logs, as hours in whole days. null goes back to a year. |
POST |
/api/v1/billing/ask |
Asks for more than your plan allows. Owners only, once a day. |
An invite is emailed. The reply leaves out the invite link, because anyone who
holds it can join. If the email didn’t go, the reply has a note saying so.
Revoke that invite and invite them from the app, where you’ll see the link once.
You can set an SSO domain over the API. Proving you own it means signing in to Google, so you do that in the app.
What stays in the app
Section titled “What stays in the app”A few things need the app. Most of them create a credential or show a secret once. The API stores the reply to every write for 24 hours, so a retry gets the same answer, and a secret shouldn’t be stored like that.
- Making API tokens, team tokens and GitHub trust rules.
POST /api/v1/tokensgets400. - Adding a connector, which shows its enrolment token once.
POST /api/v1/connectorsgets400. - Creating a webhook trigger. Rotating one’s secret or signing key is
PUT /api/v1/triggers/{id}. - Proving an SSO domain and claiming a GitHub App installation. Both sign in to Google or GitHub in your browser.
- Billing checkout and the billing portal. Their links sign whoever holds them in to your team’s billing.
- Making a team or switching teams. A token belongs to the team it was made in.
- Signing in, signing up, MFA, passkeys, passwords, approving a CLI login and accepting an invite.
- Starting a builder test run. Test runs don’t count towards your monthly executions, so a token can’t start one.
Following a run live is a stream in the app. Over the API, poll
GET /api/v1/runs/{id}.
Idempotency keys
Section titled “Idempotency keys”Every write needs an Idempotency-Key header, or you get 400 and nothing
happens. Use a new one, such as a UUID, per request. Up to 255 characters.
If a request times out, retry with the same key. You get the first response back and the work isn’t done twice.
- A repeated key returns the original response with
Idempotency-Replayed: true. - The same key with a different method, path or body gets
409. - The same key while the first request is still running gets
409. Retry shortly. - Keys last 24 hours.
- A failed request frees its key, so fix the problem and retry with the same key.
Replays count towards your rate limit.
Rate limits
Section titled “Rate limits”Each request counts against two budgets per one-minute window: yours and your team’s.
| Plan | Per user | Per team |
|---|---|---|
| Free | 30 | 60 |
| Developer | 120 | 300 |
| Production | 300 | 1200 |
| Business | 1200 | 6000 |
Responses show whichever budget you’re closest to using up:
| Header | Description |
|---|---|
X-RateLimit-Limit |
Requests allowed in the window. |
X-RateLimit-Remaining |
Requests left in the window. |
X-RateLimit-Reset |
When the window resets, as a Unix timestamp. |
Over the limit you get 429 with Retry-After in seconds.
Any request with a valid token counts, even one refused for a missing scope. A
401, or the 403 for a token whose owner left the team, doesn’t count and has
no rate-limit headers.
GET /api/tokens/usage shows your
budget for free.
Errors
Section titled “Errors”Errors are JSON with an error message, and sometimes a code.
| Status | Meaning |
|---|---|
400 |
The request is malformed. For example an undeclared body field, a missing required field, a bad timestamp, a body over 1 MiB (the file upload takes more) or a missing Idempotency-Key. |
401 |
The Authorization header is missing, or the token is unknown, expired or revoked. |
402 |
Your plan doesn’t include what you asked for. The message says what it is, the cheapest plan that has it, the steps that need it if any, and that a team owner can change the plan under Team settings, Billing. |
403 |
The token lacks the scope, you’ve left the token’s team or your role doesn’t allow the action. |
404 |
The resource doesn’t exist or isn’t visible to you. Dagweave doesn’t tell the two apart. |
409 |
An Idempotency-Key conflict, a stale baseVersion, a rerun that can’t reuse its input files, a run the cluster isn’t set up for, a change to a workflow linked to Git, or a Git file that changed under you. |
413 |
An artifact is too big to read through the API. |
422 |
A save failed the draft check. The body lists the faults. |
429 |
You’re over the rate limit (with Retry-After), or over a plan limit on workflows or monthly executions (without). |
502 |
The cluster or the log backend refused or failed. |
503 |
A connector is offline or a service is unavailable. See below. |
Anything that compiles a workflow can return 503 with
"code": "compute_busy" and Retry-After: 6 when the compiler is busy. That’s
validate, create, update, run, rerun, run now, decompile, the expression checks,
deploy-schedule, the three imports, publishing a WorkflowTemplate, decompose and
Push to Git. Retry the same request.
Every endpoint above is also an MCP tool at POST /api/v1/mcp, with the same
tokens, scopes and rate limits. See MCP server.