API Reference

RESTful API for all Placino operations: project management, data ingestion, queries, and audit retrieval.

Base URL

https://placino.your-domain.com/api/v1

Authentication

All requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Get API Key

API keys issued via admin console. Each key has expiry date and optional IP whitelist.

Key Rotation

Rotate keys every 90 days. Old key remains valid during rotation window (7 days) to prevent outages.

OAuth 2.0 (Optional)

For web applications, use OAuth 2.0 authorization code flow. Placino supports standard OpenID Connect discovery.

Request/Response Format

All requests and responses use JSON. Timestamps in ISO 8601 UTC format.

Request Headers

Content-Type: application/json

Authorization: Bearer YOUR_API_KEY

X-Request-ID: unique-request-id (optional)

Success Response (200 OK)

{ "status": "success", "data": {...}, "timestamp": "2025-04-12T10:30:00Z" }

Error Response (400+)

{ "status": "error", "code": "INVALID_EPSILON", "message": "Epsilon budget exceeded" }

Rate Limiting

API rate limits apply per API key:

Default: 100 requests/minute

Burst: 200 requests/minute for 10 seconds

Large datasets: 10 concurrent ingestion jobs max

Rate limit info returned in response headers:

X-RateLimit-Limit: 100

X-RateLimit-Remaining: 42

X-RateLimit-Reset: 1712937600

Common Response Codes

200 OK: Request succeeded.

201 Created: Resource created (project, dataset).

400 Bad Request: Invalid parameters.

401 Unauthorized: Missing or invalid API key.

403 Forbidden: User lacks permission for resource.

404 Not Found: Resource does not exist.

429 Too Many Requests: Rate limit exceeded.

Pagination

List endpoints return paginated results:

/api/v1/projects?page=1&limit=25&sort=-created_at

Response includes total_count, page, pages metadata.

API Endpoints Overview

Placino API covers these resource types:

Projects & Datasets

Create projects, manage datasets, configure ingestion sources.

Data Ingestion

Upload CSV, Parquet, connect Kafka, PostgreSQL CDC, BigQuery.

Queries

Template queries, SQL, natural language, aggregations.

Audit & Logs

Retrieve immutable audit trail, permission logs, usage reports.

Explore Endpoint Details

See detailed endpoint specifications, request/response examples, and error codes:

View All Endpoints