API reference¶

In short

Everything the app does has an HTTP endpoint under /api. The interactive list is at /docs on your server, such as http://localhost:8000/docs.
In open mode, calls need no credential. Once sign-in is on, send an API token as Authorization: Bearer mlc_….
A token has a scope: analyst reads, compute also runs bounded calculations, builder builds inside the workspaces it is bound to. No token can promote a model, delete, change settings or mint tokens.
Agents normally use the MCP tools at /mcp, which wrap the same API.

Choose an interface¶

Interface	Documentation	Use it for
HTTP REST	Below and the interactive console at `/docs` on your server	Scripts and integrations with other systems
MCP	MCP tools and connection guides	Giving an agent access to ParleML
ML4 Python	ML4 reference	Training, configuration, feature engineering and scoring in code
MLI Python	MLI reference	Profiling, explanations, evaluation and model cards in code
Server settings	Configuration and settings keys	Environment variables and the Settings pages

For terms used on these pages, see the glossary.

HTTP REST API¶

The web app is a client of this API, so anything you can do in the app has an endpoint.

Where it is¶

All endpoints are under /api on the address ParleML is served at, for example http://localhost:8000/api. They take and return JSON.

Path	What it is
`/api/health`	Liveness and versions. Always open.
`/docs`	The interactive console: every endpoint, parameter and schema, with Try it out.
`/redoc`	The same reference as a readable document.
`/openapi.json`	The machine-readable OpenAPI description, for generating a client.

The console and /openapi.json are the complete list (more than 300 endpoints). They describe the shape of the API, not any workspace's data, so they are open without a credential.

Authenticate¶

How you authenticate depends on the server's sign-in mode. Settings → Access → Sign-in shows which one it is.

Open mode. Sign-in is off. Calls need no credential.
Sign-in required. Send an API token:
```
Authorization: Bearer mlc_…
```

An administrator mints tokens under Settings → Access → API tokens. The token is shown once. Choose the narrowest Scope:

Scope	It can	Lifetime
`analyst`	Read, and run read-only SQL	Until revoked
`compute`	Read, plus bounded calculations: signal checks, drift comparison, single-row predictions, what-if and cost simulations	Until revoked
`builder`	Also build in the workspaces it is bound to: run experiments from a plan, explain, score, publish, register models, edit recipes and column roles	30 days by default, at most 90

Check who you are, and with which scope:

curl -s http://localhost:8000/api/auth/me -H "Authorization: Bearer $TOKEN"

In open mode, the answer is:

{"user": {"user_id": "anon", "email": null, "display_name": "anonymous (auth off)",
          "role": "admin", "source": "anonymous"},
 "auth_required": false, "token_scope": null}

Details: what a token can never do

Whatever its scope, a token cannot promote or archive a model, rerun or delete anything, change settings or connections, mint tokens, or upload files to the server. It also cannot download files people download in the app: experiment artifacts, scored batch files, the model package. Those calls return 403 for a token. They stay a person's acts in the app.

Every builder request that changes something must carry an Idempotency-Key header (at most 200 characters). A retry with the same key replays the first answer instead of doing the work twice. See Tokens and scopes.

A worked call¶

List the workspaces, then run read-only SQL against one. Set $TOKEN to your token, or drop the -H line in open mode.

1. List workspaces: GET /api/workspaces

curl -s http://localhost:8000/api/workspaces -H "Authorization: Bearer $TOKEN"

[
  {
    "workspace_id": "a81ef7b2ce35bd8a",
    "name": "Insurance claims fraud",
    "risk_level": "Low",
    "n_datasets": 2,
    "n_experiments": 3,
    "n_models": 1,
    "stage": {"id": "operate", "label": "Operate", "position": 5, "of": 5}
  }
]

The answer has more fields, such as the business goal and the best experiment.

2. Query the workspace's data: POST /api/workspaces/{workspace_id}/query

It takes one SELECT. The tables are the workspace's datasets and published results. The result is capped at 1,000 rows, so check has_more.

curl -s -X POST http://localhost:8000/api/workspaces/a81ef7b2ce35bd8a/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "select table_name from information_schema.tables limit 3"}'

{
  "columns": ["table_name"],
  "rows": [
    {"table_name": "claims_complementary_native_roster_archetypes"},
    {"table_name": "claims_complementary_native_roster_predictions"},
    {"table_name": "claims_local_incident_sentence_meaning_followup_archetypes"}
  ],
  "n_returned": 3,
  "has_more": false
}

3. Read an experiment: GET /api/experiments/{experiment_id}

It returns the name, status, target, dataset, primary metric, validation and test scores, and the full configuration. GET /api/experiments?workspace_id=<workspace-id> lists a workspace's experiments.

Conventions¶

IDs are opaque strings such as a81ef7b2ce35bd8a. The IDs in the app's address bar are the ones the API uses.
Errors are JSON with a machine-readable code, a message and optional details:
```
{"code": "not_found", "message": "Workspace 'nope' not found", "details": {}}
```
401 means no usable credential. 403 means the token's scope or the server's policy forbids the call. 429 with budget_exceeded means a builder token reached a limit; details names it.
Long work (training, explanations, scoring) returns at once and runs as a background job. Read the object's status until it finishes. Don't hold a request open for the result.
Result limits. Query results stop at 1,000 rows and chart data at 2,000 points per series, so a caller can't pull an unbounded table. Both are settings.
Versions. The API is this installation's version, shown by /api/health. Generate clients from this server's /openapi.json, and generate them again after an upgrade.

Agents and MCP¶

An agent normally uses ParleML through its MCP tools at /mcp, not the REST endpoints. The tools wrap the same API, with the same token scopes, and add guidance on how to use them. Settings → Access → Your own agent has a ready configuration for Claude Desktop, claude.ai, Claude Code, Cursor, ChatGPT, Codex, Gemini CLI and a local (stdio) server.

Next¶

Use ParleML from Claude Code: an agent of your own, through MCP.
Configuration and settings keys: the server's environment variables.