REST API Reference

Data Island exposes 128+ stateless JSON REST endpoints organized into logical categories. All endpoints are rate-limitable, audited, and secured through the Gatekeeper API gateway.

Base URL

http://localhost:8050/api

All endpoint paths below are relative to this base URL. In production, replace localhost:8050 with your Gatekeeper address.

Authentication

Every API request must include authentication credentials. Three methods are supported:

Common Response Format

All endpoints return JSON. Successful responses include a data field; errors include error and message.

{
  "status": "ok",
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "duration_ms": 42
  }
}

{
  "status": "error",
  "error": "NOT_FOUND",
  "message": "Table 'nonexistent' does not exist.",
  "meta": {
    "request_id": "req_def456"
  }
}

Tables

Create, list, describe, and manage tables in your organization.

Data Operations

Write, read, and query data. The query endpoint accepts standard SQL.

Query Example

curl -X POST http://localhost:8050/api/data/query \
  -H "Authorization: Bearer st_tok_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT sensor_id, AVG(temperature) FROM sensors GROUP BY sensor_id",
    "format": "json"
  }'

Ingestion

Upload files (CSV, Parquet, JSON) for bulk data ingestion.

RBAC & Access Control

Manage roles, users, permissions, and API keys.

Monitoring

Health checks, metrics, and operational endpoints.

Rate Limiting

The Gatekeeper enforces per-key rate limits. When a limit is exceeded, the API responds with HTTP 429 Too Many Requests and includes a Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706500000

Next Steps