# Athena Athena API

Source: https://userguide.qualytics.io/source-datastore/datastore/jdbc/athena/how-tos/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](https://userguide.qualytics.io/source-datastore/datastore/api/).

> **Tip: Complete API Reference**
>
> For the full interactive API documentation with all request/response schemas, visit the [API docs](https://userguide.qualytics.io/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, plus the **Editor** team permission on at least one of the assigned teams (the **Public** team when `teams` is left out). Admins are exempt.

---

## 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 | Yes |  | Athena HTTPS port. Send `443`. The request is rejected with `422` when `port` is missing, even though the add-source form fills in `443` for you. |
| `database` | string | Yes |  | AWS Data Catalog name (**the catalog**, not the database). In the UI, select or type a catalog such as `AwsDataCatalog`. The API needs the value sent explicitly. |
| `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. |

> **Note: About trigger_sync**
>
> The `trigger_sync: 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 (such as PostgreSQL or Snowflake) as the Athena source's destination, see [Datastore API › Link Enrichment Destination](https://userguide.qualytics.io/source-datastore/datastore/api/#link-an-enrichment-destination).

---

## Create with a New Connection

**Tab: Access Key**

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: Example request and response**
>
> **Request**:
>
> ```bash
> 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_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "id": 42,
>   "name": "Athena Production",
>   "type": "athena",
>   "store_type": "jdbc",
>   "database": "AwsDataCatalog",
>   "schema": "production_db",
>   "connected": true
> }
> ```

**Tab: IAM Role**

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: Example request and response**
>
> **Request**:
>
> ```bash
> 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_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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](https://userguide.qualytics.io/source-datastore/datastore/jdbc/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: Example request and response**
>
> **Request**:
>
> ```bash
> 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_sync": true
>   }'
> ```
>
> **Response** (200 OK):
>
> ```json
> {
>   "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](https://userguide.qualytics.io/source-datastore/datastore/api/) reference.

*Last updated: November 3, 2026.*
