API Overview

The RAT platform exposes a REST API served by ratd (the Go API server) on port 8080. All platform operations — pipelines, runs, queries, storage, scheduling — are performed through this API. The portal communicates exclusively with this API.

Base URL

All API endpoints are prefixed with /api/v1:

http://localhost:8080/api/v1

A few endpoints live outside the /api/v1 prefix:

Authentication

RAT supports three authentication modes depending on the edition and configuration:

No Authentication (Community Default)

By default, the Community Edition requires no authentication. All endpoints are open.

API Key (Community)

When the RAT_API_KEY environment variable is set, all API requests must include the key:

curl -H "X-Api-Key: your-api-key" http://localhost:8080/api/v1/pipelines

Bearer Token (Pro Edition)

When the auth plugin is enabled (Pro Edition with Keycloak or another identity provider), all requests must include a JWT bearer token:

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." http://localhost:8080/api/v1/pipelines

Content Types

JSON (default)

All request and response bodies use JSON:

Content-Type: application/json

Multipart Form Data (file uploads)

File upload endpoints accept multipart form data:

Content-Type: multipart/form-data

Used by:

• POST /api/v1/files/upload — pipeline file upload (max 32 MB)
• POST /api/v1/landing-zones/{ns}/{name}/files — landing zone file upload (max 32 MB)
• POST /api/v1/landing-zones/{ns}/{name}/samples — sample file upload (max 32 MB)

Server-Sent Events (SSE)

The run logs endpoint supports real-time streaming via SSE when the client sends the appropriate Accept header:

Accept: text/event-stream

Used by:

• GET /api/v1/runs/{id}/logs — real-time log streaming

Error Response Format

All API errors return a structured JSON envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "type": "VALIDATION",
    "message": "Human-readable error description"
  }
}

Error Fields

Error Types by HTTP Status

Common Error Codes

Pagination

List endpoints support cursor-based pagination using limit and offset query parameters:

Example

# First page (items 0-49)
curl http://localhost:8080/api/v1/pipelines?limit=50&offset=0
 
# Second page (items 50-99)
curl http://localhost:8080/api/v1/pipelines?limit=50&offset=50

Paginated Response Shape

All paginated responses include a total count alongside the results array:

{
  "pipelines": [ ... ],
  "total": 142
}

Use total to calculate the number of pages: Math.ceil(total / limit).

Sorting

Some list endpoints support sorting via query parameters:

Example

curl "http://localhost:8080/api/v1/pipelines?sort=name&order=asc"

Available sort fields vary by endpoint — refer to each endpoint’s documentation for details.

Filtering

List endpoints support filtering via query parameters. Available filters vary by endpoint:

# Filter pipelines by namespace and layer
curl "http://localhost:8080/api/v1/pipelines?namespace=default&layer=silver"
 
# Filter runs by status
curl "http://localhost:8080/api/v1/runs?status=running"
 
# Search pipelines by name
curl "http://localhost:8080/api/v1/pipelines?search=orders"

Refer to each endpoint’s documentation for the full list of supported filters.

Rate Limiting

When rate limiting is enabled, all responses include rate limit headers:

Example 429 Response

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
Retry-After: 30
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "type": "RATE_LIMIT",
    "message": "Too many requests. Retry after 30 seconds."
  }
}

SSE Streaming

The run logs endpoint supports Server-Sent Events for real-time log streaming. To enable SSE, set the Accept header:

curl -H "Accept: text/event-stream" http://localhost:8080/api/v1/runs/{id}/logs

SSE Event Types

SSE Format

event: log
data: {"timestamp": "2026-02-12T14:00:01Z", "level": "info", "message": "Starting pipeline silver.orders"}

event: log
data: {"timestamp": "2026-02-12T14:00:02Z", "level": "info", "message": "Executing SQL..."}

event: status
data: {"status": "success", "rows_written": 12340, "duration_ms": 4500}

For active runs, the SSE stream keeps the connection open and polls for new logs every 2 seconds until the run reaches a terminal state (success, failed, or cancelled).

JSON Fallback

Without the Accept: text/event-stream header, the logs endpoint returns a standard JSON response with all available logs:

{
  "logs": [
    {"timestamp": "2026-02-12T14:00:01Z", "level": "info", "message": "Starting pipeline silver.orders"}
  ],
  "status": "success"
}

File Uploads

File upload endpoints use multipart/form-data encoding with a maximum file size of 32 MB.

Example: Upload a Pipeline File

curl -X POST http://localhost:8080/api/v1/files/upload \
  -F "path=default/pipelines/silver/orders/data.csv" \
  -F "file=@/local/path/to/data.csv"

Example: Upload to a Landing Zone

curl -X POST http://localhost:8080/api/v1/landing-zones/default/raw-uploads/files \
  -F "file=@/local/path/to/orders.csv"

Files exceeding 32 MB receive a 413 response:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "type": "VALIDATION",
    "message": "file too large (max 32MB)"
  }
}

API Endpoint Summary