Data Platform API — Xentropy Docs

The Data Platform API lets you query your Delta Lake data warehouse, manage data-source connectors, and trigger data syncs.

#

https://api.xentropy.ai/api/data-platform

All endpoints require authentication. Additionally, every request must include an X-Tenant-Id header set to your tenant ID.

| Header | Value | Required | |--------|-------|----------| | Authorization | Bearer <jwt-token> | Yes | | X-Tenant-Id | <your-tenant-id> | Yes | | Content-Type | application/json | For POST/PATCH |

#

All errors return a consistent shape:

{
  "statusCode": 403,
  "message": "Tenant access denied",
  "error": "forbidden"
}

| Status | Error Code | Meaning | |--------|-----------|---------| | 400 | query_execution_error | Invalid SQL or execution failure | | 403 | forbidden | Tenant mismatch or auth failure | | 404 | table_not_found | Referenced Delta table does not exist | | 408 | query_timeout | Query exceeded timeout | | 503 | service_unavailable | Worker unreachable |

#

POST /api/data-platform/query

Executes a read-only SQL query against your tenant's Delta Lake.

#

{
  "sql": "SELECT event_type, count(*) AS cnt FROM events GROUP BY event_type",
  "params": { "1": "value" },
  "maxRows": 10000,
  "timeoutSeconds": 30
}

| Field | Type | Default | Description | |-------|------|---------|-------------| | sql | string | — | Read-only SQL (SELECT, WITH, DESCRIBE, EXPLAIN, SHOW) | | params | object | {} | Named parameters for ? placeholders | | maxRows | integer | 10000 | Max result rows (0-100000) | | timeoutSeconds | integer | 30 | Query timeout (0 disables, max 60) |

#

{
  "columns": [
    { "name": "event_type", "type": "VARCHAR", "nullable": true },
    { "name": "cnt", "type": "BIGINT", "nullable": false }
  ],
  "rows": [
    { "event_type": "click", "cnt": 4500 }
  ],
  "rowCount": 1,
  "executionTimeMs": 15.3
}

#

curl -X POST https://api.xentropy.ai/api/data-platform/query \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT count(*) AS n FROM events"}'

#

| Code | HTTP Status | Meaning | |------|-------------|---------| | query_timeout | 408 | Query exceeded timeoutSeconds | | permission_denied | 403 | Query contains DDL/DML | | table_not_found | 404 | Referenced table doesn't exist | | query_execution_error | 400 | Invalid SQL or DuckDB error |

#

GET /api/data-platform/schema

Returns the unified schema — all tables across all connectors with column names and types.

#

{
  "tables": [
    {
      "name": "events",
      "columns": [
        { "name": "id", "type": "int8", "nullable": false },
        { "name": "event_type", "type": "text", "nullable": true }
      ],
      "rowCount": 15000
    }
  ]
}

#

curl https://api.xentropy.ai/api/data-platform/schema \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: <tenant-id>"

#

POST /api/data-platform/sync

Triggers a full data sync for all connectors belonging to your tenant. Returns a job ID that can be polled for status.

#

{
  "jobId": "a1b2c3d4e5f678901234567890abcdef",
  "status": "pending",
  "startedAt": "2026-06-22T10:30:00Z"
}

#

curl -X POST https://api.xentropy.ai/api/data-platform/sync \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: <tenant-id>"

#

GET /api/data-platform/sync/{jobId}

Returns the current status of an async sync job.

#

{
  "jobId": "a1b2c3d4e5f6...",
  "status": "running",
  "progress": 0.6,
  "startedAt": "2026-06-22T10:30:00Z",
  "completedAt": null,
  "error": null
}

#

| Status | Meaning | |--------|---------| | pending | Job created, waiting for dispatch | | running | Sync in progress | | completed | Sync finished successfully | | failed | Sync failed (check error field) |

#

GET /api/data-platform/connectors

Returns all data-source connectors configured for your tenant.

#

[
  {
    "id": "a1b2c3d4e5f6...",
    "name": "My Supabase",
    "type": "supabase",
    "enabled": true,
    "config": { "sync_interval_seconds": 300 },
    "createdAt": "2026-06-01T12:00:00Z",
    "updatedAt": "2026-06-22T10:00:00Z"
  }
]

#

| Type | Description | |------|-------------| | supabase | Supabase PostgREST API | | postgres | Direct Postgres connection (coming soon) | | mysql | MySQL connection (coming soon) | | bigquery | Google BigQuery (coming soon) | | snowflake | Snowflake (coming soon) | | csv | CSV file upload (coming soon) | | api | Generic REST API (coming soon) |

#

POST /api/data-platform/connectors

#

{
  "name": "My Supabase Project",
  "type": "supabase",
  "config": {
    "supabase_url": "https://abc123.supabase.co",
    "service_role_key": "eyJhbG...NiIs...",
    "sync_interval_seconds": 300
  }
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Human-friendly display name | | type | string | Yes | Connector type (see types above) | | config | object | Yes | Source-specific configuration |

#

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | supabase_url | string | Yes | — | Supabase project URL | | service_role_key | string | Yes | — | Service role JWT (bypasses RLS) | | sync_interval_seconds | integer | No | 300 | Sync interval in seconds |

#

Returns the created ConnectorConfig with the auto-generated id.

#

PATCH /api/data-platform/connectors/{connectorId}

Update an existing connector's configuration.

#

{
  "name": "Updated Name",
  "enabled": false,
  "config": {
    "sync_interval_seconds": 900
  }
}

All fields are optional — omitted fields keep their current values.

#

DELETE /api/data-platform/connectors/{connectorId}

Removes the connector configuration. The existing Delta tables are not deleted.

#

Returns 204 No Content on success.

#

| Tier | Requests per minute | |------|---------------------| | Free | 30 | | Pro | 300 |

Query endpoints (/query, /schema) have a concurrency limit of 5 simultaneous requests per tenant.