Skip to main content

Platform API Overview

The Platform API is the central API for Alien Intelligence. It handles authentication, organization management, dataset catalog, cluster orchestration, workflow execution, and AI model registry.

Base URLs​

EnvironmentURL
Productionhttps://app.alien.club
Staginghttps://staging.alien.club
Localhttp://localhost:3333

Authentication​

Most endpoints require a Bearer token in the Authorization header. Two token types are supported — both provide the same authorization context.

API Tokens (Programmatic Access)​

For scripts, SDKs, and integrations, create an API token from the Keys section in the dashboard (see Manage Your Organization).

curl -H "Authorization: Bearer oat_YOUR_API_TOKEN" \
  https://app.alien.club/datasets

API tokens are prefixed with oat_ and do not expire unless you set an expiration at creation time.

OAuth JWT (Web Sessions)​

The web interface authenticates automatically via OAuth2 + OIDC through Authentik. You don't need to manage JWT tokens manually — the frontend handles token refresh.

Public Endpoints​

A few endpoints work without authentication (datasets, AI models, tags, providers, licenses, sources). These return only publicly visible resources. If you include a valid token, they also return your organization's private resources.

Response Format​

All endpoints return a consistent JSON envelope:

Success
{
  "success": true,
  "data": { ... }
}
Success with pagination
{
  "success": true,
  "meta": {
    "currentPage": 1,
    "total": 42,
    "perPage": 100,
    "lastPage": 1
  },
  "data": [ ... ]
}
Error
{
  "success": false,
  "message": "Resource not found",
  "error": {
    "status": 404
  }
}
Validation error
{
  "success": false,
  "message": "Validation failure",
  "error": {
    "status": 422,
    "messages": [
      { "field": "name", "rule": "required", "message": "The name field is required" }
    ]
  }
}

Slug-Based Access​

Most resources support access by both numeric ID and slug:

# By ID
GET /workflows/42

# By slug
GET /workflows/slug/my-workflow

Slugs must match the pattern ^[a-z0-9_-]+$ (lowercase alphanumeric, hyphens, underscores).

Batch Operations​

Most resource endpoints support batch fetching by IDs or slugs via query parameters:

GET /datasets/batch?ids=1,2,3
GET /workflows/batch?slugs=my-workflow,other-workflow

Cluster Proxy​

The Platform API includes a transparent proxy that forwards requests to data clusters:

ANY /clusters/{cluster_id}/proxy/*

This is the primary way to access the Data API for Alien Hosted deployments. The proxy authenticates, authorizes, and logs every request. It injects identity headers (x-user-id, x-organization-id, etc.) so the data cluster knows who is calling.

curl -X POST "https://app.alien.club/clusters/5/proxy/api/v1/search" \
  -H "Authorization: Bearer oat_YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "machine learning", "limit": 10}'

Timeouts: 30s for GET/PATCH/PUT/DELETE, 120s for POST.

External API Proxy​

The platform can also proxy requests to configured external APIs (third-party services):

POST /external-apis/{connectorId}/endpoints/{endpointId}/proxy

This provides metered access to external APIs with billing tracking via the x-billed-units response header. Max response size: 50MB.

Endpoint Reference​

The full endpoint reference with interactive documentation, request/response schemas, and code samples is available in the sidebar. Endpoints are grouped by resource:

  • Workflows — CRUD, run (async/sync), presets, metrics, consumption
  • Jobs — Status, results, SSE streaming, compute context
  • Nodes — Available workflow node types and their schemas
  • Collections — Dataset collection management with routing info
  • Datasets — Dataset catalog (public read, authenticated write)
  • Entries — Dataset entry management and file access
  • AI Models — Model registry with provisioned credentials
  • Cluster Proxy — Transparent proxy to data clusters
  • External API Proxy — Metered proxy to third-party APIs
  • Access Tokens — API token lifecycle management
  • Clusters — Cluster listing and details

Next Steps​