Athena API

This page documents Athena-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/response schemas, visit the API docs.

Athena supports two authentication types — Access Key (default) and IAM Role. You can create a datastore with a new inline connection or reuse an existing connection. All three modes 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 mistake (sending the database name where the catalog name belongs).

UI form field	API field	AWS concept	Example
Connection > Host	`connection.host`	Athena regional endpoint	`athena.us-east-1.amazonaws.com`
Connection > S3 Output Location	`connection.parameters.output`	S3 query-results location	`s3://my-athena-results/`
Datastore > Catalog	`database`	AWS Data Catalog name	`AwsDataCatalog`
Datastore > Database	`schema`	Database (schema) inside the catalog	`production_db`
Connection > Type	`connection.parameters.authentication_type`	Selects between Access Key (`BASIC`) and IAM Role (`IAM_ROLE`)	`BASIC`
Connection > Access Key ID	`connection.username`	AWS Access Key ID (Access Key auth)	`AKIA…`
Connection > Secret Access Key	`connection.password`	AWS Secret Access Key (Access Key auth)	`wJalrXUt…`
Connection > Role ARN	`connection.parameters.role_arn`	Target role for STS AssumeRole (IAM Role auth)	`arn:aws:iam::123456789012:role/MyRole`
Connection > External ID	`connection.parameters.external_id`	Optional external ID enforced by trust policy	`my-external-id`

Connection Fields

Property	Type	Required	Default	Description
`host`	string	Yes	—	Athena regional endpoint built from your region (e.g., `athena.us-east-1.amazonaws.com`). VPC endpoint URLs and private DNS aliases are not supported.
`port`	integer	No	`443`	Athena HTTPS port.
`database`	string	Yes	—	AWS Data Catalog name — the catalog, not the database (e.g., `AwsDataCatalog`).
`schema`	string	Yes	—	Database name within the catalog (the value shown as Database in the UI).
`parameters.authentication_type`	string	No	`BASIC`	`BASIC` (Access Key) or `IAM_ROLE`.
`parameters.output`	string	Yes	—	S3 Output Location where Athena writes query results (e.g., `s3://my-bucket/`).
`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`	—	AWS Access Key ID.
`password`	string	If `BASIC`	—	AWS Secret Access Key.

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.

Note

Athena cannot be used as an enrichment datastore. To link a separate enrichment datastore (e.g., PostgreSQL or Snowflake) to your Athena source, see Datastore API › Link Enrichment Datastore.

Create with a New Connection

Access KeyIAM Role

The default authentication type. Use when you can provide static AWS credentials with permissions for Athena, Glue, and the query-results S3 bucket. Pass the AWS Access Key ID as username and the Secret Access Key as 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": "Athena Production",
    "connection": {
      "name": "athena_production",
      "type": "athena",
      "host": "athena.us-east-1.amazonaws.com",
      "port": 443,
      "username": "AKIAIOSFODNN7EXAMPLE",
      "password": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE",
      "parameters": {
        "authentication_type": "BASIC",
        "output": "s3://my-athena-results/"
      }
    },
    "database": "AwsDataCatalog",
    "schema": "production_db",
    "teams": ["Data Platform"],
    "trigger_catalog": true
  }'

Response (201 Created):

{
  "id": 42,
  "name": "Athena Production",
  "type": "athena",
  "store_type": "jdbc",
  "database": "AwsDataCatalog",
  "schema": "production_db",
  "connected": true
}

Authenticate via AWS STS by assuming an IAM role. Qualytics uses short-lived credentials that refresh automatically before they expire. Use this for cross-account access, environments that disallow long-lived keys, or to avoid storing static AWS credentials in Qualytics.

Set parameters.authentication_type to "IAM_ROLE" and provide the role ARN. Omit username and password — they are not used in this mode. 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": "Athena Production",
    "connection": {
      "name": "athena_production",
      "type": "athena",
      "host": "athena.us-east-1.amazonaws.com",
      "port": 443,
      "parameters": {
        "authentication_type": "IAM_ROLE",
        "role_arn": "arn:aws:iam::123456789012:role/QualyticsAthenaRole",
        "external_id": "<your-external-id>",
        "output": "s3://my-athena-results/"
      }
    },
    "database": "AwsDataCatalog",
    "schema": "production_db",
    "teams": ["Data Platform"],
    "trigger_catalog": true
  }'

Response (201 Created):

{
  "id": 42,
  "name": "Athena Production",
  "type": "athena",
  "store_type": "jdbc",
  "database": "AwsDataCatalog",
  "schema": "production_db",
  "connected": true
}

Warning

The host must be the canonical Athena endpoint for your region (athena.<region>.amazonaws.com). VPC endpoint URLs (vpce-…) and custom Route 53 / private DNS aliases are not supported. See Athena Authentication for the full setup walkthrough.

Note

If role_arn is provided but authentication_type is not set to "IAM_ROLE", the role is ignored and the connection falls back to Access Key authentication. Always set authentication_type explicitly when using IAM Role.

Create with an Existing Connection

If you have already created an Athena connection (via this API or the UI), reuse it by passing its connection_id. The authentication type and credentials are reused from the existing connection — you only need to specify datastore-level fields like database, schema, and teams.

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": "Athena Finance",
    "connection_id": 7,
    "database": "AwsDataCatalog",
    "schema": "finance_db",
    "teams": ["Finance Team"],
    "trigger_catalog": true
  }'

Response (201 Created):

{
  "id": 43,
  "name": "Athena Finance",
  "type": "athena",
  "store_type": "jdbc",
  "database": "AwsDataCatalog",
  "schema": "finance_db",
  "connected": true
}

Other Operations

For get, list, update, delete, test connection, multi-schema bulk creation, and end-to-end automation examples, see the Datastore API reference.