API Reference

This reference documents the CorePlexML REST API for developers building integrations, automating ML workflows, or consuming predictions. All endpoints accept and return JSON unless otherwise noted (file uploads use multipart/form-data).

Base URL

All paths in this documentation are relative to a configurable base URL. The default for local development is:

http://localhost:8888

In production the base URL is typically behind a reverse proxy with TLS, for example https://ml.example.com. All example curl commands below use the shell variable $BASE_URL which you should set to your own host:

export BASE_URL="http://localhost:8888"

Authentication

CorePlexML supports two authentication mechanisms:

Session cookies – Used by the web UI. Call POST /api/auth/login to obtain a session cookie that is automatically sent on subsequent requests.

Bearer tokens (API keys) – Recommended for programmatic access. Create an API key through POST /api/auth/api-keys and include it in every request via the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys carry scopes that restrict which operations they can perform. Available scopes: read, write, predict, admin.

Note

API key management endpoints (create/list/revoke) use cookie session auth and CSRF protection. See Authentication for the exact flow.

See Authentication for the full auth API.

Common Response Format

List endpoints return paginated results with a consistent envelope:

{
  "items": [ "..." ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Single-resource endpoints wrap the resource in a named key:

{
  "project": { "id": "...", "name": "..." }
}

Mutating endpoints that do not return a resource body return a confirmation:

{
  "ok": true
}

Pagination

Most list endpoints accept the following query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Maximum number of items to return (1–500).
`offset`	integer	0	Number of items to skip.
`search`	string	–	Free-text search (case-insensitive substring match).
`sort_field`	string	`created_at`	Column to sort by. Allowed values vary per endpoint.
`sort_direction`	string	`desc`	`asc` or `desc`.

Content Types

Request body – application/json for all endpoints except file uploads.
File uploads – multipart/form-data (datasets, batch predict).
Responses – application/json unless the endpoint returns a binary file (CSV, PDF, XLSX, ZIP).

Rate Limiting

Endpoints are rate-limited per authenticated user using a fixed-window strategy. The server returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on every response.

When the limit is exceeded, the server responds with HTTP 429 Too Many Requests and includes a Retry-After header.

Default rate limits (configurable by server administrator):

Endpoint Category	Limit	Description
General API	100/minute	Default for all endpoints not listed below.
Authentication	10/minute	Login, register, forgot-password. Prevents brute-force.
Predictions	50/minute	Model and deployment prediction endpoints.
AutoML Training	5/minute	Experiment creation (each starts a background job).
Report Generation	20/minute	Report creation (each starts a background job).
Dataset Builder (AI)	30/minute	AI-assisted data preparation endpoints.

File Upload Limits

Upload Type	Max Size	Description
Dataset CSV/Parquet	500 MB	Configurable via `MAX_DATASET_UPLOAD_BYTES` environment variable.
Batch prediction file	100 MB	CSV file for batch predictions.

Supported upload formats: CSV (.csv) and Parquet (.parquet).

Error Handling

Errors are returned as JSON with an appropriate HTTP status code. The standard error body contains a detail field:

{
  "detail": "Project not found"
}

See Error Handling for the full list of status codes and common error scenarios.

PDF Download

API Reference PDF (EN): /pdfs/coreplexml-api-reference-en.pdf

Endpoints