# Databases (/docs/reference/api/databases)



Databases [#databases]

Reads require read permission. Creation, storage checks, and deletion require admin permission.

GET `/v1/databases` [#get-v1databases]

List databases available in the API key's cluster. Requires a readable API key
(`admin`, `read_write`, or `read_only`) or an authenticated organization member.

Each database includes `s3_storage` when it has an explicit database-level
customer-owned storage override. The value is `null` when the database inherits
the cluster's default storage. This metadata contains only bucket and path
values; storage credentials are never returned.

The response also includes RawTree's `system` database for read-only
inspection. The service does not allow this database to be deleted.

```json
{
  "databases": [
    {
      "name": "default",
      "s3_storage": null
    },
    {
      "name": "system",
      "s3_storage": null
    },
    {
      "name": "analytics",
      "s3_storage": {
        "data": { "bucket": "acme-rawtree-data", "path": "rawtree/data" },
        "backups": { "bucket": "acme-rawtree-backups", "path": "rawtree/backups" }
      }
    }
  ]
}
```

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# List databases in an organization.
curl -X GET "https://api.rawtree.com/v1/databases" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "databases": [
    {
      "name": "analytics",
      "s3_storage": null
    }
  ]
}
```

Errors: `400`, `401`, `403`. See [API errors](/docs/reference/errors).

POST `/v1/databases` [#post-v1databases]

Create a database. API-key authentication requires `admin` permission.

```json
{ "name": "analytics" }
```

To give the database its own customer-owned S3 storage, include `s3_storage`.
Tables in the database inherit this configuration. The service uses the External ID
saved when the cluster was created; do not send `external_id` in database requests.
The cluster must have a saved identity, and the customer IAM role's trust policy
must require that cluster's External ID. Tag both database buckets and the role
with `rawtree.com/cluster=<resource_tag>` from the cluster response.

```json
{
  "name": "analytics",
  "s3_storage": {
    "data": { "bucket": "acme-rawtree-data", "path": "rawtree/data" },
    "backups": { "bucket": "acme-rawtree-backups", "path": "rawtree/backups" },
    "role_arn": "arn:aws:iam::123456789012:role/RawTreeS3Access"
  }
}
```

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Parameters:

| Field        | Location | Type                   | Required | Notes |
| ------------ | -------- | ---------------------- | -------- | ----- |
| `name`       | body     | string                 | Yes      | —     |
| `s3_storage` | body     | null or S3StorageInput | No       | —     |

Request:

```bash
# Create a database in an organization.
curl -X POST "https://api.rawtree.com/v1/databases" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "analytics"
}'
```

Expected response: **HTTP 200**.

```json
{
  "database": {
    "name": "analytics"
  }
}
```

Errors: `400`, `401`, `403`, `409`. See [API errors](/docs/reference/errors).

POST `/v1/databases/verify-s3-access` [#post-v1databasesverify-s3-access]

Verify customer-owned S3 access before creating a database. Send the same `name`
and `s3_storage` fields as database creation above. The backend loads the selected
cluster's saved External ID automatically. API-key authentication requires
`admin` permission.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Parameters:

| Field        | Location | Type                   | Required | Notes |
| ------------ | -------- | ---------------------- | -------- | ----- |
| `name`       | body     | string                 | Yes      | —     |
| `s3_storage` | body     | null or S3StorageInput | No       | —     |

Request:

```bash
# Verify customer-owned S3 access for a database.
curl -X POST "https://api.rawtree.com/v1/databases/verify-s3-access" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "analytics",
  "s3_storage": {
    "data": {
      "bucket": "acme-rawtree-data",
      "path": "rawtree/data"
    },
    "backups": {
      "bucket": "acme-rawtree-backups",
      "path": "rawtree/backups"
    },
    "role_arn": "arn:aws:iam::123456789012:role/RawTreeS3Access"
  }
}'
```

Expected response: **HTTP 200**.

```json
{
  "verified": true,
  "message": "S3 access verified."
}
```

Errors: `400`, `401`, `403`. See [API errors](/docs/reference/errors).

DELETE `/v1/databases/{database}` [#delete-v1databasesdatabase]

Delete a database and its data. Requires admin permission. Deleting a database
does not revoke the cluster-wide API keys that could access it.
The managed `default` database cannot be deleted.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in [Authentication](/docs/reference/authentication#existing-database-roles).

Request:

```bash
# Delete a database from an organization.
curl -X DELETE "https://api.rawtree.com/v1/databases/analytics" \
  -H "Authorization: Bearer $RAWTREE_API_KEY"
```

Expected response: **HTTP 200**.

```json
{
  "deleted": true
}
```

Errors: `400`, `401`, `403`. See [API errors](/docs/reference/errors).