Skip to main content

ClearML REST API Reference

The API reference pages are split into two main sections:

ClearML Rest Objects​

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

Service Definitions​

ClearML's REST API provides the following services:

  • Authentication - Authentication management, authorization and administration for the entire system.
  • Debug - Debugging utilities.
  • Projects - Support for defining Projects containing Tasks, Models and Dataset Versions.
  • Queues - Queue management API (see Workers Service).
  • Workers - API for worker machines to report status and retrieve tasks for execution.
  • Events - Event (e.g. metrics, debug samples) reporting and retrieval API.
  • Models - Model management API.
  • Tasks - Task Management API.

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).