RDD Scheduling API

The RDD Scheduling API was built to enable more scalable management of scan scheduling using standard CRUD functions, allowing you to choose the best times and cadence to scan your data sources.

This also assumes you've set up integrations whose schedule you wish to manage.

For an example using Terraform, see Using Terraform below.

API Conventions

All URLs listed in the documentation should have the same base URL that precedes each route. This consists of your organization's DataGrail URL along with the API version:

https://${yoursubdomain}.datagrail.io/api/v2

Authorization

In order to use this API, you must first set up an RDD agent. An agent's associated API key is required to authenticate and authorize requests to this API. The API key will be required as a bearer token in the Authorization header.

Create a Schedule

POST a cron expression to perform data discovery scans for a given integration. If successful, the newly created schedule's ID will be returned.

Endpoint

POST /api/v2/integrations/:id/schedules

Headers

Parameter	Description
Authorization	string (required) Your bearer token.

Path Parameters

Parameter	Description
id	UUID (required) The integration ID.

Body Parameters

Parameter	Description
schedule_for	string (required) Job type: `objects_scan`
cron_expression	string (required) The cron expression. All times are UTC. Range and step values supported (`-`, `/`).
start_date	string ISO 8601 date string (YYYY-MM-DD) specifying when scans can start. Default: date of schedule creation.
end_date	string ISO 8601 date string (YYYY-MM-DD). Default: `null`. Use this value to pause scans, setting to `null` can resume after `start_date`.

cron Expressions

In the cron expression, be sure to set numeric values for minutes and hours to avoid scanning systems every minute/hour. We recommend scanning at most once a week.

Example Request

# first of the month, 1AM UTC every quarter
curl -XPOST "https://${yoursubdomain}.datagrail.io/api/v2/integrations/<uuid>/schedules" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "schedule_for": "objects_scan",
      "cron_expression": "0 1 1 1/3 *"
  }'

Example Response - 200 OK

{
  "cron_expression": "0 1 1 1/3 *",
  "schedule_for": "objects_scan",
  "start_date": null,
  "end_date": null,
  "id": "5373f707-54e5-46bc-953e-90fbbb7c7d09"
}

List all Schedules

GET a list of schedules for an integration.

Endpoint

GET /api/v2/integrations/:id/schedules

Headers

Parameter	Description
Authorization	string (required) Your bearer token.

Path Parameters

Parameter	Description
id	UUID (required) The integration ID.

Example Request

curl -XGET "https://${yoursubdomain}.datagrail.io/api/v2/integrations/<uuid>/schedules" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response - 200 OK

[
  {
    "cron_expression": "0 1 1 1/3 *",
    "schedule_for": "objects_scan",
    "start_date": null,
    "end_date": null,
    "id": "5373f707-54e5-46bc-953e-90fbbb7c7d09"
  },
  ...
]

Get a Schedule

GET a schedule for an integration

Endpoint

GET /api/v2/integrations/:id/schedules/:sid

Headers

Parameter	Description
Authorization	string (required) Your bearer token.

Path Parameters

Parameter	Description
id	UUID (required) The integration ID.
sid	UUID (required) The schedule ID.

Example Request

curl -XGET "https://${yoursubdomain}.datagrail.io/api/v2/integrations/<uuid>/schedules/<sid>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response (200 OK)

{
  "cron_expression": "0 1 1 1/3 *",
  "schedule_for": "objects_scan",
  "start_date": null,
  "end_date": null,
  "id": "5373f707-54e5-46bc-953e-90fbbb7c7d09"
}

Update a Schedule

UPDATE the schedule of an integration.

Endpoint

PUT /api/v2/integrations/:id/schedules/:sid

Headers

Parameter	Description
Authorization	string (required) Your bearer token.

Path Parameters

Parameter	Description
id	UUID (required) The integration ID.
sid	UUID (required) The schedule ID.

Body Parameters

Parameter	Description
schedule_for	string (required) Job type: `objects_scan`
cron_expression	string (required) The cron expression. All times are UTC. Range and step values supported (`-`, `/`).
start_date	string ISO 8601 date string (YYYY-MM-DD) specifying when scans can start. Default: date of schedule creation.
end_date	string ISO 8601 date string (YYYY-MM-DD). Default: `null`. Use this value to pause scans, setting to `null` can resume after `start_date`.

cron Expressions

In the cron expression, be sure to set numeric values for minutes and hours to avoid scanning systems every minute/hour. We recommend scanning at most once a week.

Example Request

# 20th of every month, 11:15PM UTC
# scans start in September, 2025
curl -XPUT "https://${yoursubdomain}.datagrail.io/api/v2/integrations/<uuid>/schedules" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>" \
  -d '{
      "schedule_for": "objects_scan",
      "cron_expression": "15 23 20 * *",
      "start_date": "2025-09-01"
  }'

Example Response - 200 OK

{
  "cron_expression": "15 23 20 * *",
  "schedule_for": "objects_scan",
  "start_date": "2025-09-01",
  "end_date": null,
  "id": "5373f707-54e5-46bc-953e-90fbbb7c7d09"
}

Delete a Schedule

DELETE an integration schedule and use DataGrail defaults

Endpoint

DELETE /api/v2/integrations/:id/schedules/:sid

Headers

Parameter	Description
Authorization	string (required) Your bearer token.

Path Parameters

Parameter	Description
id	UUID (required) The integration ID.
sid	UUID (required) The schedule ID.

Example Request

curl -XDELETE "https://${yoursubdomain}.datagrail.io/api/v2/integrations/<uuid>/schedules/<sid>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <api_key>"

Example Response (200 OK)

{}

Error Codes

This API uses the following error codes:

Code	Description
401	Unauthorized -- Your API key is incorrect or invalid.
404	Not Found -- The integration could not be found. Confirm the route or integration id are correct.
422	Unprocessable Entity -- The request body cannot be processed. Ensure that you're passing the correct parameters.
500	Internal Server Error -- An internal and unexpected error condition occurred.

Using Terraform

To configure your integrations and their schedules for your data sources, below is an example that uses the terraform-provider-restapi.

When resources are modified, the appropriate API calls are made to add, remove and update schedules.

To configure the token and hostname, use environment variables (TF_VAR_*) or your preferred, secured method.

terraform {
  required_providers {
    restapi = {
      source  = "mastercard/restapi"
      version = "~> 1.19.1"
    }
  }
}

variable "dg_agent_token" {
  type        = string
  description = "The API token of the RDD Agent."
}

variable "dg_api_hostname" {
  type        = string
  description = "Your API hostname, eg, yoursubdomain.datagrail.io"
}

provider "restapi" {
  alias                = "datagrail_rdd_api"
  uri                  = "https://${var.dg_api_hostname}/"
  debug                = true
  write_returns_object = true

  headers = {
    Authorization      = "Bearer ${var.dg_agent_token}",
    "Content-Type"     = "application/json"
  }
}

resource "restapi_object" "example_postgres_scanner" {
  provider  = restapi.datagrail_rdd_api
  path      = "/api/v2/data_discovery/integrations"
  data      = jsonencode({
    name                  = "postgres-test-api-01"
    credentials_location  = "arn:example"
    connector_type        = "postgres"
  })
}

resource "restapi_object" "example_postgres_schedule" {
  provider  = restapi.datagrail_rdd_api
  path      = "/api/v2/integrations/${restapi_object.example_postgres_scanner.id}/schedules"
  data      = jsonencode({
    schedule_for          = "objects_scan"
    cron_expression       = "0 0 * * 7"
  })
}

Need help?

If you have any questions, please reach out to your dedicated Account Manager or contact us at support@datagrail.io.

Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material.

API Conventions​

Authorization​

Create a Schedule​

Endpoint​

Headers​

Path Parameters​

Body Parameters​

Example Request​

Example Response - 200 OK​

List all Schedules​

Endpoint​

Headers​

Path Parameters​

Example Request​

Example Response - 200 OK​

Get a Schedule​

Endpoint​

Headers​

Path Parameters​

Example Request​

Example Response (200 OK)​

Update a Schedule​

Endpoint​

Headers​

Path Parameters​

Body Parameters​

Example Request​

Example Response - 200 OK​

Delete a Schedule​

Endpoint​

Headers​

Path Parameters​

Example Request​

Example Response (200 OK)​

Error Codes​

Using Terraform​

API Conventions

Authorization

Create a Schedule

Endpoint

Headers

Path Parameters

Body Parameters

Example Request

Example Response - 200 OK

List all Schedules

Endpoint

Headers

Path Parameters

Example Request

Example Response - 200 OK

Get a Schedule

Endpoint

Headers

Path Parameters

Example Request

Example Response (200 OK)

Update a Schedule

Endpoint

Headers

Path Parameters

Body Parameters

Example Request

Example Response - 200 OK

Delete a Schedule

Endpoint

Headers

Path Parameters

Example Request

Example Response (200 OK)

Error Codes

Using Terraform