Skip to content

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.