Delete DAGs
Delete DAGs API
| Article ID | RC-API-30 — Delete DAGs API |
|---|---|
| Domain | API |
| Applies To | All REDCap projects with Data Access Groups enabled |
| Requires | Any supported version |
| Verified Against | REDCap v17.5.6 (Standard) — §1, §2, §4–§6 live-tested via the API on a sandbox project (2026-10); LTS line last reviewed against the v17.3.7 (LTS) changelog |
| Prerequisite | RC-API-01 — REDCap API |
| Version | 1.2 |
| Last Updated | 2026-10 |
| Author | See KB-SOURCE-ATTESTATION.md |
| Source | REDCap API v16.1.3 official documentation examples |
| Related Topics | RC-API-01 — REDCap API; RC-DAG-01 — Data Access Groups; RC-DE-09 — Data Entry with Data Access Groups |
| Synonyms | how do i delete dags via the api; delete data access groups api call; remove dags from a project through the api; api method to delete data access groups by unique group name; bulk delete dags with the api; clean up unused data access groups programmatically; api endpoint to delete data access groups; remove data access groups via api; records missing after deleting dag api; delete dags api non-existent dag error |
1. Overview¶
The Delete DAGs API method removes Data Access Groups from your project. You provide a list of DAG unique group names (the unique_group_name values) to delete. This method deletes the DAG definition itself. Users and records assigned to that DAG are not deleted, but they lose the DAG association. Use this method to clean up unused DAGs, automate DAG lifecycle management, or remove groups after consolidation.
Caution: Deleting a DAG is a significant operation. Users in deleted DAGs may lose their data isolation context. Ensure this is intended before deletion.
2. Parameters¶
| Parameter | Required | Description |
|---|---|---|
token |
Required | Your project API token. Requires API Import/Update and Data Access Groups privileges at the project level. |
content |
Required | Always 'dag' for this method. |
action |
Required | Always 'delete' for this method. |
dags[0], dags[1], ... |
Required | Array of unique group names to delete. Pass as dags[0]=group_1&dags[1]=group_2, etc. |
3. Request Examples¶
3.1 Python¶
from config import config
import requests, json
fields = {
'token': config['api_token'],
'content': 'dag',
'action': 'delete',
'format': 'json',
'dags[0]': 'group_api'
}
r = requests.post(config['api_url'],data=fields)
print('HTTP Status: ' + str(r.status_code))
print(r.text)
3.2 R¶
#!/usr/bin/env Rscript
source('config.R')
library(RCurl)
result <- postForm(
api_url,
token=api_token,
content='dag',
action='delete',
'dags[0]'='group_api'
)
print(result)
3.3 cURL¶
#!/bin/sh
. ./config
DATA="token=$API_TOKEN&content=dag&action=delete&format=json&dags[0]=group_api"
$CURL -H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-X POST \
-d $DATA \
$API_URL
3.4 PHP¶
<?php
include 'config.php';
$fields = array(
'token' => $GLOBALS['api_token'],
'content' => 'dag',
'action' => 'delete',
'format' => 'json',
'dags' => array('group_api'),
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $GLOBALS['api_url']);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // Set to TRUE for production use
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_AUTOREFERER, true);
curl_setopt($ch, CURLOPT_MAXREDIRS, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);
$output = curl_exec($ch);
print $output;
Note: CURLOPT_SSL_VERIFYPEER should be TRUE in production.
4. Response¶
On success, the API returns a count of DAGs deleted. For example: 1 means one DAG was removed from the project. If any DAG name in the list does not exist, the whole call fails (HTTP 400) and no DAGs are deleted.
Example response: 1
5. Common Questions¶
Q: What happens to data records assigned to a deleted DAG?
A: The records are not deleted, but on 17.5.6 they disappear from exports: after the DAG is deleted, Export Records and Export Project XML no longer return them, even for a user with access to all DAGs. The data is still in the project (Generate Next Record Name still counts the records, and re-importing a value brings the whole record back without a DAG). Reassign or unassign the records (redcap_data_access_group blank in an import) before deleting the DAG.
Q: What is the unique_group_name?
A: It's the system-generated identifier assigned to the DAG (e.g., 'group_1', 'boston_site'). To find this ID, export existing DAGs using the Export DAGs method (RC-API-28 — Export DAGs API).
Q: What if I try to delete a DAG that doesn't exist?
A: The call fails with HTTP 400 One or more of the dags provided are not valid unique group names that do not exist in this project. Note: No dags were deleted. DAGs that do not exist: … — and any valid DAGs in the same call are not deleted either.
Q: Can I delete multiple DAGs at once?
A: Yes. Pass multiple unique group names using array syntax: dags[0]=group_1&dags[1]=group_2. All DAGs in the array will be deleted in a single call.
Q: Can I undo a DAG deletion?
A: No. DAG deletion is permanent. To restore a DAG, you must import it again using the Import DAGs method (RC-API-29 — Import DAGs API) with the same or similar definition. Records that lost their DAG assignment cannot automatically regain it.
Q: What permissions do I need?
A: Your API token must have both API Import/Update and Data Access Groups privileges enabled at the project level. Having only one of the two is not sufficient.
6. Common Mistakes & Gotchas¶
Deleting a DAG without reassigning its users or records. Users lose the DAG association. Records still assigned to the DAG vanish from exports (see Common Questions), so unassign them first. Before deleting a DAG in production, export users and records to identify what is affected. If users need to retain data isolation, reassign them to alternative DAGs or adjust record assignments.
Confusing DAG display names with unique group names. The unique_group_name is the system ID (e.g., 'boston_site'), not the human-readable label (e.g., 'Boston Site'). Use the ID, not the label, in the delete request.
Including a DAG name that doesn't exist. One unknown unique group name makes the whole call fail with HTTP 400, and nothing is deleted. Export the DAGs first and only send names from that list.
Forgetting the correct permissions. This method requires both API Import/Update and Data Access Groups privileges. Having only one is not sufficient — the deletion will fail if either is missing.
Inadvertently deleting the wrong DAG. DAG names are easy to mistype. Always verify the correct unique group name by exporting existing DAGs before deletion.
Deleting a DAG that users are currently active in. If a user is actively viewing or entering data in a DAG you delete, their session context may become inconsistent. Notify users before deleting DAGs or ensure they switch to another DAG first.
7. Related Articles¶
- RC-API-01 — REDCap API (foundational; required reading before using any API method)
- RC-DAG-01 — Data Access Groups (explains DAG concepts, structure, and configuration)
- RC-DE-09 — Data Entry with Data Access Groups (covers data entry constraints in DAG-enabled projects)
- RC-API-28 — Export DAGs API (retrieve existing DAG definitions and their unique names)
- RC-API-29 — Import DAGs API (create or update DAG definitions)
- RC-API-31 — Export User-DAG Assignments API (identify which users are assigned to DAGs)
- RC-API-32 — Import User-DAG Assignments API (assign users to DAGs)
- RC-USER-03 — User Rights: Configuring User Privileges (reference for permission types)