API Reference

The Digital Tap AI REST API lets you manage platforms, clusters, optimization settings, and retrieve savings reports programmatically.

Authentication

All API requests require authentication. Include your token in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.digitaltap.ai/v1/account

You can generate API keys from the Dashboard Settings page. Two types of tokens are supported:

• Session JWT: Short-lived tokens from Supabase auth (used by the dashboard)
• API Key: Long-lived keys for programmatic access (prefixed with dtap_)

Account

Returns account info including name, email, plan, and organizations.

{
  "id": "uuid",
  "name": "Anthony Laughlin",
  "email": "anthony@example.com",
  "plan": "growth",
  "status": "active",
  "organizations": [
    { "id": "uuid", "name": "My Org", "slug": "my-org", "role": "owner" }
  ]
}

Returns an array of usage reports with compute savings, clusters monitored, and optimization metrics.

Returns aggregate savings summary.

{
  "total_savings_usd": 47283,
  "total_water_saved_gallons": 1247832,
  "total_co2_reduced_tons": 12.4,
  "total_reports": 18
}

Platforms

Connect Databricks as a service principal, with OAuth machine-to-machine credentials. A personal access token is not accepted. Digital Tap exchanges the client ID and secret for a short-lived token and lists clusters before storing anything; if either fails it answers 422 with Databricks' reason and stores nothing. The grants are in the Databricks setup guide.

Parameter	Type	Description
platform required	string	databricks — the only platform that can be connected today
credential_type required	string	sp_oauth
credentials required	object	host (workspace URL), client_id (the service principal's application ID), client_secret (an OAuth secret)
config.warehouse_id	string	Optional: the SQL warehouse system tables are read through

curl -X POST https://api.digitaltap.ai/api/user/platforms \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "databricks",
    "credential_type": "sp_oauth",
    "credentials": {
      "host": "https://myworkspace.cloud.databricks.com",
      "client_id": "5d4c3b2a-1f0e-4d9c-8b7a-695847362514",
      "client_secret": "$DATABRICKS_CLIENT_SECRET"
    },
    "config": {"warehouse_id": "1234567890abcdef"}
  }'

Rotate a Databricks service principal's OAuth secret. Send credentials with host, client_id and the new client_secret. As at connect, the new credentials are exchanged for a token and used to list clusters before anything is stored; if either fails, the answer is 422 with Databricks' reason and nothing changes. Credentials that work but for a different workspace are refused too: connect another workspace as a new connection.

Test the connection for a platform. Returns { ok: true, cluster_count: N } on success.

Disconnect a platform and remove stored credentials.

Clusters

List all clusters across connected platforms.

{
  "clusters": [
    {
      "id": "cluster-id",
      "name": "prod-etl-pipeline",
      "platform": "Databricks",
      "status": "running",
      "workers": 4,
      "hourly_cost": 12.50,
      "idle_minutes": 0,
      "instance_type": "i3.xlarge",
      "is_spot": false,
      "tags": { "region": "us-east-1" }
    }
  ],
  "platforms": 3
}

Savings & Reports

Returns time-series usage reports for charting savings over time.

[
  {
    "period_start": "2026-04-01",
    "period_end": "2026-04-07",
    "compute_savings_usd": 3200,
    "clusters_monitored": 12,
    "clusters_optimized": 8
  }
]

Monitoring & Optimization

Returns monitoring status and current configuration.

{
  "enabled": true,
  "platforms_connected": 3,
  "clusters_monitored": 12,
  "actions_last_24h": 7,
  "config": {
    "auto_hibernate": true,
    "auto_rightsize": true,
    "auto_spot_failover": false,
    "idle_threshold_pct": 15
  }
}

Update monitoring configuration.

Parameter	Type	Description
auto_hibernate	boolean	Auto-hibernate idle clusters
auto_rightsize	boolean	Auto-rightsize underutilized clusters
auto_spot_failover	boolean	Auto-migrate to spot instances
idle_threshold_pct	number	Utilization % below which a cluster is considered idle (default: 15)

Cluster Actions

Hibernate a specific cluster.

Resume a hibernated cluster.

Apply right-sizing recommendation to a cluster.

Billing

Returns current plan, period stats, payment method, and history.

Create a Stripe checkout session for upgrading to Growth plan.

Create a Stripe billing portal session for managing subscription.

Webhooks

Configure webhooks from the Dashboard Settings to receive real-time notifications for:

• cluster.hibernated — A cluster was auto-hibernated
• cluster.rightsized — A cluster was right-sized
• cluster.alert — A cluster issue was detected
• savings.milestone — A savings milestone was reached
• scan.complete — A platform scan completed