REST API

The LakeOps REST API gives you programmatic access to everything in the platform — catalogs, tables, compaction, policies, observability, and queries. Use it to integrate LakeOps into CI/CD pipelines, scripts, or your own applications.

Base URL

Each region has its own API host. Use the host that matches the region where your organization was created.

RegionBase URL
US East (N. Virginia)https://api.lakeops.dev
EU West (Ireland)https://api-eu.lakeops.dev
Asia Pacific (Mumbai)https://api-in.lakeops.dev

Authentication

Every request must include an API key as a Bearer token in the Authorization header. Create API keys in Organization > API Keys.

Example request

curl https://api.lakeops.dev/api/catalogs \
  -H "Authorization: Bearer lk_your_api_key"
•Keys are scoped to an organization and region — a US East key only works against api.lakeops.dev.
•Keys carry permission scopes (see Permissions & scopes). Calls without the required scope return 403 Forbidden.
•Unauthenticated or invalid requests return 401 Unauthorized.

Response format

All responses are JSON. Successful requests return the resource directly. Errors return a JSON object with an error field:

// Success (200)
{
  "catalogs": [
    { "name": "production-glue", "tableCount": 142, "totalSize": "2.4 TB", ... }
  ]
}

// Error (403)
{
  "error": "scope 'catalogs:read' required"
}

Endpoints

The API is organized by domain. Each group shows the minimum scope required.

Catalogs

catalogs:readcatalogs:write
MethodPath
GET/api/catalogs
POST/api/catalogs
PUT/api/catalogs/{name}
DELETE/api/catalogs/{name}
GET/api/config/catalog/{name}
POST/api/refresh/catalog/{name}

Tables

tables:readtables:write
MethodPath
GET/api/search
GET/api/namespaces/{catalogName}
GET/api/namespaces/{catalogName}/{namespacePath}
GET/api/distribution/{catalogName}/{namespace}/{tableName}
GET/api/partition-distribution/{catalogName}/{namespace}/{tableName}
GET/api/table-metrics
POST/api/refresh/table/{catalogName}/{namespace}/{tableName}
DELETE/api/tables/{catalogName}/{namespace}/{tableName}
POST/api/tables/{catalogName}/{namespace}/{tableName}/rename
PUT/api/tables/{catalogName}/{namespace}/{tableName}/properties
DELETE/api/tables/{catalogName}/{namespace}/{tableName}/properties

Compaction

tables:write
MethodPath
POST/api/compaction/{catalogName}/{namespace}/{tableName}
GET/api/compaction/job/{jobId}

Snapshot management

tables:write
MethodPath
POST/api/tables/{catalogName}/{namespace}/{tableName}/rollback-to-snapshot
POST/api/tables/{catalogName}/{namespace}/{tableName}/rollback-to-timestamp
POST/api/tables/{catalogName}/{namespace}/{tableName}/set-current-snapshot
DELETE/api/tables/{catalogName}/{namespace}/{tableName}/branches/{branchName}
DELETE/api/tables/{catalogName}/{namespace}/{tableName}/tags/{tagName}

Observability

read
MethodPath
GET/api/dashboard
GET/api/monitoring/maintenance-summary
GET/api/monitoring/maintenance-samples
GET/api/monitoring/operations-stats
GET/api/insights/search
GET/api/insights/{catalogName}/{namespace}/{tableName}
GET/api/tables/{catalogName}/{namespace}/{tableName}/maintenance
GET/api/events
GET/api/events/timeline
GET/api/events/storage-timeline
GET/api/tables/{catalogName}/{namespace}/{tableName}/events

Query

query:read
MethodPath
POST/api/query/{catalogName}

Policies

policies:readpolicies:write
MethodPath
GET/api/policies
POST/api/policies/{type}
GET/api/policies/{type}/{id}
PUT/api/policies/{type}/{id}
DELETE/api/policies/{type}/{id}
GET/api/tables/{catalogName}/{namespace}/{tableName}/policies
POST/api/tables/{catalogName}/{namespace}/{tableName}/policies/{type}
PUT/api/tables/{catalogName}/{namespace}/{tableName}/policies/{type}/{id}
POST/api/tables/{catalogName}/{namespace}/{tableName}/policies/{type}/{id}/enable
POST/api/tables/{catalogName}/{namespace}/{tableName}/policies/{type}/{id}/disable
POST/api/tables/{catalogName}/{namespace}/{tableName}/policies/{type}/{id}/execute

Examples

List all catalogs

curl https://api.lakeops.dev/api/catalogs \
  -H "Authorization: Bearer $LAKEOPS_API_KEY"

Search tables by health status

curl "https://api.lakeops.dev/api/search?status=CRITICAL&catalog=production-glue" \
  -H "Authorization: Bearer $LAKEOPS_API_KEY"

Get table health insights

curl https://api.lakeops.dev/api/insights/production-glue/analytics/page_events \
  -H "Authorization: Bearer $LAKEOPS_API_KEY"

Trigger compaction

curl -X POST https://api.lakeops.dev/api/compaction/production-glue/analytics/page_events \
  -H "Authorization: Bearer $LAKEOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "BINPACK",
    "targetFileSizeBytes": 536870912,
    "maxConcurrentFileGroupRewrites": 5
  }'

Create a compaction policy

curl -X POST https://api.lakeops.dev/api/policies/COMPACT_DATA_FILES \
  -H "Authorization: Bearer $LAKEOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-compaction",
    "catalogName": "production-glue",
    "schedule": "0 2 * * *",
    "config": {
      "strategy": "BINPACK",
      "targetFileSizeBytes": 536870912
    }
  }'

Run an ad-hoc SQL query

curl -X POST https://api.lakeops.dev/api/query/production-glue \
  -H "Authorization: Bearer $LAKEOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT COUNT(*) FROM analytics.page_events WHERE dt = '''2026-08-30'''"
  }'

Get the org-wide dashboard

curl https://api.lakeops.dev/api/dashboard \
  -H "Authorization: Bearer $LAKEOPS_API_KEY"

# Response includes:
# - tableHealth: { healthy, warning, critical }
# - storageReclaimed, operationsCount, querySpeedGain
# - recentEvents, topInsights

GitHub Actions integration

Automate table maintenance as part of your CI/CD pipeline. Store your API key as a GitHub Actions secret and call the REST API from workflow steps.

1. Add the API key as a secret

Go to your repository's Settings > Secrets and variables > Actions and add a secret named LAKEOPS_API_KEY.

2. Example workflow

This workflow runs nightly: checks for tables with critical health status, triggers compaction on any that need it, and posts a summary to Slack.

# .github/workflows/lakeops-maintenance.yml
name: LakeOps Nightly Maintenance

on:
  schedule:
    - cron: "0 3 * * *"    # 3 AM UTC daily
  workflow_dispatch:         # manual trigger

env:
  LAKEOPS_API: https://api.lakeops.dev
  CATALOG: production-glue

jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - name: Check table health
        id: health
        run: |
          RESPONSE=$(curl -s "$LAKEOPS_API/api/search?status=CRITICAL&catalog=$CATALOG" \
            -H "Authorization: Bearer ${{ secrets.LAKEOPS_API_KEY }}")
          echo "critical_tables=$(echo $RESPONSE | jq '.tables | length')" >> $GITHUB_OUTPUT
          echo "$RESPONSE" | jq '.tables[].name' > critical_tables.txt

      - name: Trigger compaction on critical tables
        if: steps.health.outputs.critical_tables > 0
        run: |
          while IFS= read -r table; do
            table=$(echo "$table" | tr -d '"')
            echo "Compacting $table..."
            curl -s -X POST "$LAKEOPS_API/api/compaction/$CATALOG/${table}" \
              -H "Authorization: Bearer ${{ secrets.LAKEOPS_API_KEY }}" \
              -H "Content-Type: application/json" \
              -d '{"strategy":"BINPACK","targetFileSizeBytes":536870912}'
          done < critical_tables.txt

      - name: Get dashboard summary
        run: |
          curl -s "$LAKEOPS_API/api/dashboard" \
            -H "Authorization: Bearer ${{ secrets.LAKEOPS_API_KEY }}" | \
            jq '{healthy: .tableHealth.healthy, warning: .tableHealth.warning, critical: .tableHealth.critical, storageReclaimed: .storageReclaimed}'

More CI/CD patterns

•Pre-deploy health gate— add a step that fails the pipeline if critical tables exceed a threshold.
•Post-ingestion compaction— trigger compaction after your data pipeline writes new data.
•Policy enforcement— use the policies API to create or update governance policies as part of infrastructure-as-code workflows.
•Monitoring & alerting— query the insights API to detect regressions in table health.

Rate limits & best practices

  • •Use the narrowest scope possible when creating API keys. A key that only needs to read table health should have tables:read and read, not write.
  • •Set an expiration on keys used in CI/CD. Rotate regularly.
  • •Store keys in secret managers (GitHub Secrets, AWS Secrets Manager, Vault) — never commit them to source control.
  • •For high-frequency polling, prefer the /api/dashboard endpoint over individual table queries.

Next steps

  • •MCP Server Setup — connect AI agents to these same APIs via Model Context Protocol.
  • •Policies — define governance rules that the API can create and manage.
  • •Agentic AI — understand how AI agents interact with your data lake through LakeOps.
← Agentic AINext: MCP Server →