Redshift API

This page documents Redshift-specific payload fields for the datastore API. For generic operations (get, list, update, delete, multi-schema bulk), see Datastore API.

Complete API Reference

For the full interactive API documentation with all request and response schemas, visit the API docs.

Redshift supports two authentication types (Password by default, or IAM Role) and can be created either as a source datastore (read-only) or as an enrichment datastore (read-write). You can create a datastore with a new inline connection or reuse an existing connection. All flows use the same endpoint:

Endpoint: POST /api/datastores

Permission: Manager

UI ↔ API field mapping

The API names a few fields differently from the UI. The mapping below avoids the most common copy-paste mistakes when switching from the form to the JSON payload.

UI form field	API field	Notes	Example
Connection > Connection Name	`connection.name`	Saved-connection label. Optional.	`redshift_production`
(set by connector choice)	`connection.type`	Connector identifier. Always `"redshift"` for Redshift.	`redshift`
Connection > Host	`connection.host`	Cluster endpoint hostname.	`your-cluster.abc123.us-east-1.redshift.amazonaws.com`
Connection > Port	`connection.port`	Integer. Defaults to `5439`.	`5439`
Datastore > Database	`database`	The Redshift database (top-level in payload, not under `connection`).	`your_database`
Datastore > Schema	`schema`	The Redshift schema (top-level).	`public`
Connection > Type	`connection.parameters.authentication_type`	`BASIC` (Password) or `IAM_ROLE`. Defaults to `BASIC` when omitted.	`BASIC`
Connection > User	`connection.username`	Redshift database user. Required only when `authentication_type` is `BASIC`.	`qualytics_read`
Connection > Password	`connection.password`	Redshift database password. Required only when `authentication_type` is `BASIC`.	`...`
Connection > Role ARN	`connection.parameters.role_arn`	Target role for STS AssumeRole. Required when `authentication_type` is `IAM_ROLE`.	`arn:aws:iam::123456789012:role/MyRole`
Connection > External ID	`connection.parameters.external_id`	Optional external ID enforced by the role's trust policy.	`<your-external-id>`
Datastore > Initiate Sync	`trigger_catalog`	When `true`, syncs metadata immediately after creation.	`true`

When authentication_type is IAM_ROLE, omit username and password from the payload. Qualytics rewrites the JDBC URL to jdbc:redshift:iam:// automatically and obtains short-lived database credentials through the JDBC driver.

Connection Fields

Property	Type	Required	Default	Description
`host`	string	Yes		Redshift cluster endpoint hostname.
`port`	integer	No	`5439`	Redshift listening port.
`database`	string	Yes		The Redshift database name (top-level, not under `connection`).
`schema`	string	Yes		The Redshift schema name (top-level).
`parameters.authentication_type`	string	No	`BASIC`	`BASIC` (Password) or `IAM_ROLE`.
`parameters.role_arn`	string	If `IAM_ROLE`		IAM role ARN to assume via AWS STS.
`parameters.external_id`	string	No		External ID for STS AssumeRole. Include only when your trust policy requires one.
`username`	string	If `BASIC`		Redshift database user.
`password`	string	If `BASIC`		Redshift database password.

About trigger_catalog

The trigger_catalog: true flag in the examples below tells Qualytics to immediately sync metadata after creating the datastore (equivalent to ticking the Initiate Sync toggle in the UI). Set it to false if you want to defer the first sync.

Create a Source Datastore

A source datastore uses a read-only Redshift user (Password mode) or a target IAM role (IAM Role mode). Set enrichment_only: false to mark the datastore as a source.

Password (New Connection)IAM Role (New Connection)Existing Connection

Use this mode when you can supply a Redshift database user and password directly. Pass the credentials as username and password, and set authentication_type to BASIC (or omit parameters entirely, since BASIC is the default).

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Production",
    "connection": {
      "name": "redshift_production",
      "type": "redshift",
      "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
      "port": 5439,
      "username": "your_user",
      "password": "your_password",
      "parameters": {
        "authentication_type": "BASIC"
      }
    },
    "database": "your_database",
    "schema": "public",
    "teams": ["Data Platform"],
    "enrichment_only": false,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 42,
  "name": "Redshift Production",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "public",
  "enrichment_only": false,
  "connected": true
}

Authenticate via AWS STS by assuming an IAM role. Qualytics obtains short-lived database credentials that refresh automatically. Use this mode for cross-account access, environments that disallow long-lived database passwords, or to centralize Redshift access in IAM. Set parameters.authentication_type to "IAM_ROLE" and provide the role ARN. Omit username and password. The external_id field is optional and only required if your trust policy enforces it.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Production",
    "connection": {
      "name": "redshift_production",
      "type": "redshift",
      "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
      "port": 5439,
      "parameters": {
        "authentication_type": "IAM_ROLE",
        "role_arn": "arn:aws:iam::123456789012:role/QualyticsRedshiftRole",
        "external_id": "<your-external-id>"
      }
    },
    "database": "your_database",
    "schema": "public",
    "teams": ["Data Platform"],
    "enrichment_only": false,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 42,
  "name": "Redshift Production",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "public",
  "enrichment_only": false,
  "connected": true
}

Note

See Authentication and IAM Role Authentication for the trust policy setup and per-deployment base role details.

Reuse a previously created Redshift connection (via this API or the UI) by passing its connection_id at the top level instead of inlining connection: {...}. The authentication type and credentials are reused from the existing connection. You only specify datastore-level fields like database, schema, teams, and enrichment_only.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Finance",
    "connection_id": 7,
    "database": "your_database",
    "schema": "finance",
    "teams": ["Finance Team"],
    "enrichment_only": false,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 43,
  "name": "Redshift Finance",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "finance",
  "enrichment_only": false,
  "connected": true
}

Create an Enrichment Datastore

An enrichment datastore uses a read-write Redshift user (Password mode) or a target IAM role with both source and enrichment grants. Set enrichment_only: true to mark the datastore as an enrichment store.

Password (New Connection)IAM Role (New Connection)Existing Connection

Use a read-write Redshift user that holds the source grants plus the additional CREATE, INSERT, UPDATE, and DELETE privileges on the enrichment schema. Pass the credentials as username and password.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Enrichment",
    "connection": {
      "name": "redshift_enrichment",
      "type": "redshift",
      "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
      "port": 5439,
      "username": "qualytics_readwrite",
      "password": "your_password",
      "parameters": {
        "authentication_type": "BASIC"
      }
    },
    "database": "your_database",
    "schema": "qualytics_enrichment",
    "teams": ["Data Platform"],
    "enrichment_only": true,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 44,
  "name": "Redshift Enrichment",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "qualytics_enrichment",
  "enrichment_only": true,
  "connected": true
}

Set parameters.authentication_type to "IAM_ROLE" and provide a role ARN whose target Redshift user holds the enrichment grants in the database. Omit username and password. The external_id field is optional and only required if your trust policy enforces it.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Enrichment",
    "connection": {
      "name": "redshift_enrichment",
      "type": "redshift",
      "host": "your-cluster.abc123.us-east-1.redshift.amazonaws.com",
      "port": 5439,
      "parameters": {
        "authentication_type": "IAM_ROLE",
        "role_arn": "arn:aws:iam::123456789012:role/QualyticsRedshiftEnrichmentRole",
        "external_id": "<your-external-id>"
      }
    },
    "database": "your_database",
    "schema": "qualytics_enrichment",
    "teams": ["Data Platform"],
    "enrichment_only": true,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 44,
  "name": "Redshift Enrichment",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "qualytics_enrichment",
  "enrichment_only": true,
  "connected": true
}

Enrichment IAM Role permissions

The assumed role needs the AWS IAM permissions for credential issuance (provisioned: redshift:GetClusterCredentials; Serverless: redshift-serverless:GetCredentials) plus the DB-level enrichment grants (CREATE, INSERT, UPDATE, DELETE) on the target schema. See Permissions for the full IAM policy.

Reuse a previously created Redshift connection that was configured for read-write access. Pass connection_id and set enrichment_only: true.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redshift Enrichment",
    "connection_id": 7,
    "database": "your_database",
    "schema": "qualytics_enrichment",
    "teams": ["Data Platform"],
    "enrichment_only": true,
    "trigger_catalog": true
  }'

Response (200 OK):

{
  "id": 45,
  "name": "Redshift Enrichment",
  "type": "redshift",
  "store_type": "jdbc",
  "database": "your_database",
  "schema": "qualytics_enrichment",
  "enrichment_only": true,
  "connected": true
}

Other Operations

For get, list, update, delete, test connection, and link-enrichment endpoints, see the Datastore API reference.