Skip to main content

ClearML REST API Reference

The ClearML Server exposes a comprehensive REST API.

The API reference pages are split into two main sections:

Object Definitions​

See the Rest API object definitions reference page to view descriptions of the objects used in API requests:

Service Definitions​

The ClearML Open Source and Enterprise offerings each support their own API sets.

Open Source Server API Services​

  • debug - Debugging utilities.
  • events - Event reporting and retrieval (e.g., metrics, debug samples)
  • login - Authentication management, authorization and administration for the entire system.
  • models - Model management: create, edit, update metadata and tags, move, publish, archive, set visibility, and retrieve models.
  • pipelines – Pipeline management: create, update, execute, monitor, and query pipelines.
  • projects - Project management for creating, updating, retrieving, and controlling access
  • queues - Queue management (see Workers Service).
  • reports – Report management: create, update, publish, archive, move, and query Reports.
  • serving – Model serving configuration and endpoint management.
  • tasks - Task Management API.
  • workers - Worker registration, status reporting, and task execution

Enterprise Server API Services​

  • apps – ClearML UI Application templates and instance management.
  • auth – User authentication, credential management, and token generation.
  • datasets – HyperDataset management API
  • debug – Debugging utilities
  • events – Event reporting and retrieval (e.g., metrics, debug samples)
  • frames – HyperDataset frame (entry) retrieval
  • login – Authentication management, authorization and administration for the entire system.
  • models – Model management: create, edit, update metadata and tags, move, publish, archive, set visibility, and retrieve models.
  • organization – Manage organizations, users, invites, and company metadata.
  • permissions – Manage user groups, access rules, and entity-level permissions.
  • pipelines – Pipeline management: create, update, execute, monitor, and query pipelines.
  • projects – Project management API for creating, updating, organizing, querying, and controlling access to Projects
  • queues – Queue management API (see Workers Service).
  • reports – Report management API for creating, editing, publishing, archiving, moving, and querying ClearML Reports.
  • resources – Resource policies, configurations, and allocation management.
  • routers – Request routing rules and task router configuration.
  • server – Server configuration, health, status, and version information retrieval.
  • serving – Model serving configuration and endpoint management.
  • sso – Single sign-on (SSO) provider management and authentication testing.
  • storage – Storage settings and configuration management.
  • system – Companies, datasets, and system-wide configuration.
  • tasks – Task management API.
  • tenants –Tenant information retrieval
  • users – User accounts, preferences, service users, and access-related information.
  • variables – Global variables and counters management.
  • workers – Worker registration, status reporting, and task execution

Request Format​

An API request is formatted in the following way:

base_url/endpoint

Where the base_url is the api_server configured in your clearml.conf file (e.g. https://api.clear.ml) and the endpoint is as specified for the available services. The content-type is application/json.

Requests need to be authenticated with a bearer token that identifies the workspace that you want to work with. An initial request of GET /auth.login, using the basic authorization scheme generates this token to be used with all subsequent API requests. The authorization header contains Basic <credentials> where credentials is base64("<key>:<secret>") using ClearML credentials (access key and secret key).

curl -u "<access_key>:<secret_key>" -X GET https://<base_url>/auth.login

This call will return the token. By default, the token expires in 30 days. Generate a token with a shorter expiration time by specifying the expiration_sec field (as a query parameter or as a JSON payload).