=============
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:

.. code-block:: text

   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 :doc:`authentication` for the exact flow.

See :doc:`authentication` for the full auth API.

Common Response Format
----------------------

**List endpoints** return paginated results with a consistent envelope:

.. code-block:: json

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

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

.. code-block:: json

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

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

.. code-block:: json

   {
     "ok": true
   }

Pagination
----------

Most list endpoints accept the following query parameters:

.. list-table::
   :header-rows: 1
   :widths: 15 10 10 65

   * - 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):

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - 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
------------------

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - 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:

.. code-block:: json

   {
     "detail": "Project not found"
   }

See :doc:`errors` for the full list of status codes and common error
scenarios.

PDF Download
------------

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

.. toctree::
   :maxdepth: 1
   :caption: Endpoints

   authentication
   projects
   datasets
   experiments
   models
   deployments
   reports
   privacy
   synthgen
   studio
   errors