Databases

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

GET /v1/databases

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.

{
  "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.

Request:

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

Expected response: HTTP 200.

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

Errors: 400, 401, 403. See API errors.

POST /v1/databases

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

{ "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.

{
  "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.

Parameters:

Request:

# 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.

{
  "database": {
    "name": "analytics"
  }
}

Errors: 400, 401, 403, 409. See API errors.

POST /v1/databases/verify-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.

Parameters:

Request:

# 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.

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

Errors: 400, 401, 403. See API errors.

DELETE /v1/databases/{database}

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.

Request:

# 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.

{
  "deleted": true
}

Errors: 400, 401, 403. See API errors.