Write Endpoints

Note that access to the Comet REST endpoints require the {'Authorization': ${COMET_API_KEY}} header. To get your API key, see Comet Python API Setup.

Create Workspace¶

POST /api/rest/v2/write/workspace/new

Create a new workspace

Example Request

{
    "name: required": "someName",
    "plan: optional": "PLAN"
}

Example Response

{
    "code": 200,
    "msg": "saved",
    "workspace_id": "fa2c4010-017f-4c9c-9121-98e8cb0b1e65",
    "workspace_name": "new-workspace-name"
}

Note: added 2022/02/01

Create Experiment¶

POST /api/rest/v2/write/experiment/create

Create an experiment.

Example Request

{
    "experimentName, optional": "someExperimentName",
    "projectName: required": "someProjectName",
    "workspaceName: required": "someTeamName"
}

Example Response

{
    "experimentKey": "someExperimentKey",
    "link": "link to experiment",
    "projectName": "someProjectName",
    "workspaceName": "someTeamName"
}

Stop Experiment¶

GET /api/rest/v2/write/experiment/stop?experimentKey=KEY

Stop an experiment.

Example Response

{
    "msg": "Stop Requested"
}

Archive Experiment¶

GET /api/rest/v2/write/experiment/archive?experimentKey=KEY

Archive an experiment.

Example Response

{
    "msg": "Archived"
}

Move an Experiment to another Project¶

POST /api/rest/v2/write/experiment/move

Move (or symlink) an experiment to another project.

Example Request

{
    "experimentKeys: required": "[THE_KEY,ANOTHER_KEY]",
    "symlink: required": true,
    "targetProjectName: required": "TARGET_PROJECT_NAME",
    "targetWorkspaceName: required": "TARGET_WORKSPACE"
}

Example Response

"[response]"

Note: added 2022/02/01

Add Symlink to Experiment¶

GET /api/rest/v2/write/project/symlink?exerimentKey=KEY&projectName=someProjectName

Add a symlink to an experiment.

Example Response

{
    "link": "symlink to experiment under the new project"
}

Delete Experiment¶

GET /api/rest/v2/write/experiment/delete?experimentKey=KEY

Delete an experiment.

Example Response

{
    "msg": "Deleted"
}

Restore Experiment¶

GET /api/rest/v2/write/experiment/restore?experimentKey=KEY

Restore an experiment.

Example Response

{
    "msg": "Restore"
}

Create Project¶

POST /api/rest/v2/write/project/create

Create a project.

Example Request

{
    "isPublic: required": "[Boolean for whether the new project should be public]",
    "projectDescription: required": "someProjectDescription",
    "projectName: required": "someProjectName",
    "workspaceName: required": "someTeamName"
}

Example Response

{
    "projectId": "someProjectId"
}

Delete Project¶

POST /api/rest/v2/write/project/delete

Delete a project.

Example Request

{
    "deleteAllExperiments: required": "[Boolean for whether to also delete all the experiments in the project]",
    "projectName: required": "someProjectName",
    "workspaceName: required": "someTeamName"
}

Example Response

{
    "msg": "Deleted"
}

Update Project¶

POST api/rest/v2/write/project/update?projectId=someProjectId

POST api/rest/v2/write/project/update?workspaceName=wsname&projectName=pname

Update a project's metadata. Either projectId should be non null, Or both projectName and workspaceName should be non null. They should not all be null or all be non null

Example Request

{
    "isPublic: optional": "[Boolean for whether the new project should be public]",
    "newProjectDescription: optional": "someProjectDescription",
    "newProjectName: optional": "someProjectDescription",
    "projectId": "someProjectId",
    "projectName": "someProjectName",
    "workspaceName": "someTeamName"
}

Example Response

{
    "msg": "Updated"
}

Update notes for Project¶

POST /api/rest/v2/write/project/notes

Update the notes for a project.

Example Request

{
    "notes: required": "someNotesString",
    "projectId: required": "someProjectId"
}

Example Response

{
    "msg": "Saved"
}

GET /api/rest/v2/write/project/add-share-link?projectId=theProjectId

Add a share-link to a project

Example Response

{
    "shareCode": "the-code"
}

Note: added 2022/02/01

GET /api/rest/v2/write/project/delete-project-share-link?projectId=ID&shareCode=CODE

Delete an existing share-link

Example Response

"[response]"

Note: added 2022/02/01

Create Registry Model¶

POST /api/rest/v2/write/registry-model

Create a new Registry Model.

Example Request

{
    "comment": "Some Comment",
    "description": "Some Description",
    "experimentModelId": "someExperimentModelId",
    "isPublic": "[Boolean]",
    "registryModelName": "someRegistryModelName",
    "stages": [
        "production",
        "staging"
    ],
    "version": "someVersion"
}

Example Response

{
    "registryModelId": "someRegistryModelId",
    "registryModelItemId": "someRegistryModelItemId"
}

Promote Experiment Model to Registry Model¶

POST /api/rest/v2/write/registry-model/item

Promote a model from an experiment to a Registry Model as a new version.

Example Request

{
    "comment": "Some Comment",
    "experimentModelId": "someExperimentModelId",
    "registryModelName": "someRegistryModelName",
    "stages": [
        "production",
        "staging"
    ],
    "version": "someVersion"
}

Example Response

{
    "registryModelId": "someRegistryModelId",
    "registryModelItemId": "someRegistryModelItemId"
}

Update Registry Model Version¶

POST /api/rest/v2/write/registry-model/item/update

Update a Registry Model version's comment and/or stages.

Example Request

{
    "comment": "Some Comment",
    "registryModelItemId": "someRegistryModelItemId",
    "stages": [
        "production",
        "staging"
    ]
}

Example Response

"200 Ok"

Delete Registry Model Version¶

GET /api/rest/v2/write/registry-model/item/delete?modelItemId=someRegistryModelItemId

Delete a Registry Model version.

Example Response

"200 Ok"

Update Registry Model¶

POST /api/rest/v2/write/registry-model/update

Update a Registry Model's name, description, and/or visibility.

Example Request

{
    "description": "New Description",
    "isPublic": "[Boolean]",
    "registryModelId": "someRegistryModelId",
    "registryModelName": "newRegistryModelName"
}

Example Response

"200 Ok"

Update Registry Model Notes¶

POST /api/rest/v2/write/registry-model/notes

Update the notes for a Registry Model.

Example Request

{
    "notes": "A potentially very long notes string",
    "registryModelName": "someRegistryModelName",
    "workspaceName": "someWorkspaceName"
}

Example Response

"200 Ok"

Delete Registry Model¶

GET /api/rest/v2/write/registry-model/delete?workspaceName=someWorkspaceName&modelName=someRegistryModelName

Delete a Registry Model

Example Response

"200 Ok"

Get Model Registry Count¶

GET /api/rest/v2/write/registry-model/count?workspaceName=teamA

Get Model Registry count

Example Response

{
    "registryModelCount": 17
}

Add Registry Model Version Stage¶

GET /api/rest/v2/write/registry-model/item/stage?modelItemId=someRegistryModelItemId&stage=production

Add a stage to a Registry Model Version.

Example Response

"200 Ok"

Remove Registry Model Version Stage¶

GET /api/rest/v2/write/registry-model/item/stage/delete?modelItemId=someRegistryModelItemId&stage=production

Remove a stage from a Registry Model Version.

Example Response

"200 Ok"

Send Experiment Keep-Alive Signal¶

GET /api/rest/v2/write/experiment/set-status?experimentKey=KEY

Send an experiment's keep-alive signal. The response tells the client how often to send the keep-alive signal, and how often to report CPU and GPU usage. Typically, a live experiment requests that the isAliveBeatDurationMillis is around 10 seconds, and an offline experiment requests about 10 minutes. In any event, the return status will send the suggested time intervals. The isAliveBeatDurationMillis determines when an experiment is no longer shown as processing in the frontend GUI.

Example Response

{
    "cpuMonitorIntervalMillis": 68000,
    "gpuMonitorIntervalMillis": 60000,
    "isAliveBeatDurationMillis": 10000
}

Set Experiment Start and End Time¶

POST /api/rest/v2/write/experiment/set-start-end-time

Set an experiment's start and end time.

Example Request

{
    "endTimeMillis, optional": "[Long milliseconds since the Epoch at experiment end]",
    "experimentKey: required": "someExperimentKey",
    "startTimeMillis, optional": "[Long milliseconds since the Epoch at experiment start]"
}

Example Response

{
    "msg": "Saved"
}

Log Other¶

POST /api/rest/v2/write/experiment/log-other

Log a key/value other data (not a metric, system, or parameter). Note that you can only retrieve others summary data (e.g., this is not recorded as a full time series).

Example Request

{
    "experimentKey: required": "someExperimentKey",
    "key: required": "someKey",
    "timestamp, optional": "[Long milliseconds since the Epoch]",
    "value: required": "someValue"
}

Example Response

{
    "msg": "Saved"
}

Log Parameter¶

POST /api/rest/v2/write/experiment/parameter

Log a parameter name and value. Note that you can only retrieve parameters summary data (e.g., this is not recorded as a full time series).

Example Request

{
    "experimentKey: required": "someExperimentKey",
    "parameterName: required": "someParamName",
    "parameterValue: required": "someParamValue",
    "step, optional": "[Long experiment step]",
    "timestamp: optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Log Metric¶

POST /api/rest/v2/write/experiment/metric

Log a metric name and value. Metrics are the only items that are logged as a full time series. However, even metrics can be throttled if too much data (either by rate or by count) is attempted to be logged.

Example Request

{
    "context, optional": "someContext",
    "epoch, optional": "[Long experiment epoch]",
    "experimentKey: required": "someExperimentKey",
    "metricName: required": "someMetricName",
    "metricValue: required": "someMetricValue",
    "step, optional": "[Long experiment step]",
    "timestamp, optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Set HTML¶

POST /api/rest/v2/write/experiment/html

Set (or append onto) an experiment's HTML.

Example Request

{
    "experimentKey: required": "someExperimentKey",
    "html: required": "someHtml",
    "override, optional": "[Boolean if true overwrite old html, if false append]",
    "timestamp: optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Upload Asset¶

POST /api/rest/v2/write/experiment/upload-asset?experimentKey=theKey&extension=optional&step=optional&fileName=optional&context=optional&type=optional&metadata=[optional 64 bit encoded metadata blob]&overwrite=false

Upload an asset.

Example Response

{
    "msg": "Saved"
}

Upload Text Sample¶

POST /api/rest/v2/write/experiment/upload-text-sample

Upload a text sample.

Example Request

{
    "apiKey": "someApiKey",
    "content": "The text sample",
    "context, optional": "someContext",
    "experimentKey: required": "someExperimentKey",
    "metadata, optional": "[64 bit encoded metadata blob]",
    "step, optional": "[Int step]"
}

Example Response

{
    "msg": "Saved"
}

Upload Git Patch¶

POST /api/rest/v2/write/experiment/git/patch?experimentKey=theKey

Upload a git patch for this experiment.

Example Response

{
    "msg": "Saved"
}

Set System Details¶

POST /api/rest/v2/write/experiment/system-details

Set some or all of the system details.

Example Request

{
    "command, and arguments, optional, optional": [
        "myScript.py",
        "-arg",
        "theArgument"
    ],
    "executable": "/usr/local/bin/python",
    "experimentKey: required": "someExperimentKey",
    "gpuStaticInfoList, optional, optional": [
        {
            "gpuIndex: required": "[Int index]",
            "name: required": "gpu name",
            "powerLimit: required": "[Int gpu power limit]",
            "totalMemory: required": "[Int gpu total memory]",
            "uuid: required": "gpu uuid"
        }
    ],
    "hostname, optional": "someHostname",
    "installedPackages": [
        "an installed packages",
        "another installed package"
    ],
    "ip, optional": "someIp",
    "logAdditionalSystemInfoList": [
        {
            "key: required": "someKey",
            "value: required": "someValue"
        }
    ],
    "networkInterfaceIps, optional, optional": [
        "a network interface ip",
        "another network interface ip"
    ],
    "os, optional": "someOs",
    "osPackages, optional, optional": [
        "an os packages",
        "another os package"
    ],
    "osType, optional": "someOsType",
    "pid, optional": "[Int pid]",
    "pythonVersion, optional": "somePythonVersion",
    "pythonVersionVerbose, optional": "somePythonVersionVerbose",
    "user, optional": "someUser"
}

Example Response

{
    "msg": "Saved"
}

Set Git Metadata¶

POST /api/rest/v2/write/experiment/git/metadata

Set an experiment's git metadata.

Example Request

{
    "branch: required": "gitBranch",
    "experimentKey: required": "someExperimentKey",
    "origin: required": "gitOrigin",
    "parent: required": "gitParent",
    "root: required": "gitRoot",
    "user: required": "gitUser"
}

Example Response

{
    "msg": "Saved"
}

Log Output¶

POST /api/rest/v2/write/experiment/output

Log a line of standard output or standard error.

Example Request

{
    "context": "someContext",
    "experimentKey: required": "someExperimentKey",
    "outputLines, required: required": [
        {
            "localTimestamp": "[Long timestamp for this line of output]",
            "offset": "[Long used to order lines of output]",
            "output": "someOutput",
            "stderr": "[Boolean true is this was stdout, false if this was stderr]"
        }
    ]
}

Example Response

{
    "msg": "Saved"
}

Log Graph¶

POST /api/rest/v2/write/experiment/graph

Log an experiment's associated model graph.

Example Request

{
    "experimentKey": "someExperimentKey",
    "graph": "someGraph"
}

Example Response

{
    "msg": "Saved"
}

Set Code¶

POST /api/rest/v2/write/experiment/code

Set an experiment's associated source code.

Example Request

{
    "code": "someCode",
    "experimentKey": "someExperimentKey"
}

Example Response

{
    "msg": "Saved"
}

Add Tags¶

POST /api/rest/v2/write/experiment/tags

Add a list of tags to an experiment.

Example Request

{
    "addedTags, optional": [
        "someTag",
        "anotherTag"
    ],
    "experimentKey": "someExperimentKey"
}

Example Response

{
    "msg": "Saved"
}

Set a Cloud Detail Item¶

POST /api/rest/v2/write/experiment/cloud-details

Set one of the cloud detail items

Example Request

{
    "experimentKey": "someExperimentKey",
    "metadata": {
        "key": "value"
    },
    "provider": "aws"
}

Example Response

"[response]"

Note: added 2022/02/01

Set an Experiment's File-path¶

POST /api/rest/v2/write/experiment/file-path

Set the file-path of an experiment

Example Request

{
    "experimentKey": "someExperimentKey",
    "filePath": "/tmp/1.py"
}

Example Response

"[response]"

Note: added 2022/02/01

Add GPU Metrics¶

POST /api/rest/v2/write/experiment/gpu-metrics

Add an instance of GPU usage metrics.

Example Request

{
    "context: optional": "someContext",
    "epoch: optional": "[Long experiment epoch]",
    "experimentKey: required": "someExperimentKey",
    "gpus": [
        {
            "freeMemory: required": "[Long]",
            "gpuId: required": "[Int identifier]",
            "gpuUtilization: required": "[Int percentage utilization]",
            "totalMemory: required": "[Long]",
            "usedMemory: required": "[Long]"
        }
    ],
    "step: optional": "[Long experiment step]",
    "timestamp: optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Add RAM Metrics¶

POST /api/rest/v2/write/experiment/ram-metrics

Add an instance of RAM usage metrics.

Example Request

{
    "context: optional": "someContext",
    "epoch: optional": "[Long experiment epoch]",
    "experimentKey: required": "someExperimentKey",
    "step: optional": "[Long experiment step]",
    "timestamp: optional": "[Long milliseconds since the Epoch]",
    "totalRam: required": "[Long]",
    "usedRam: required": "[Long]"
}

Example Response

{
    "msg": "Saved"
}

Add CPU Metrics¶

POST /api/rest/v2/write/experiment/cpu-metrics

Add an instance of CPU usage metrics.

Example Request

{
    "context: optional": "someContext",
    "cpuPercentUtilization: required": [
        "12",
        "99",
        "[Int percentage, ordered by cpu]"
    ],
    "epoch: optional": "[Long experiment epoch]",
    "experimentKey: required": "someExperimentKey",
    "step: optional": "[Long experiment step]",
    "timestamp: optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Add Processor Load Metrics¶

POST /api/rest/v2/write/experiment/load-metrics

Add an instance of processor load metrics.

Example Request

{
    "context: optional": "someContext",
    "epoch: optional": "[Long experiment epoch]",
    "experimentKey: required": "someExperimentKey",
    "loadAverage: required": "[Double]",
    "step: optional": "[Long experiment step]",
    "timestamp: optional": "[Long milliseconds since the Epoch]"
}

Example Response

{
    "msg": "Saved"
}

Update or Insert Artifact¶

POST /api/rest/v2/write/artifacts/upsert

Update an existing artifact or insert a new artifact

Example Request

{
    "artifactName": "someArtifactName",
    "artifactType": "dataframe",
    "experimentKey": "someExperimentKey",
    "isPublic": false,
    "version": "1.0.0"
}

Example Response

"[response]"

Note: added 2022/02/01

Set Artifact State¶

POST /api/rest/v2/write/artifacts/state

Set the state of an artifact

Example Request

{
    "artifactVersionId": "8bb9aa15-12d8-4068-ae85-5474232ccb00",
    "experimentKey": "someExperimentKey",
    "isPublic": false,
    "state": "CLOSED"
}

Example Response

"[response]"

Note: added 2022/02/01

Save Store¶

POST /api/rest/v2/write/viz-instance/store/save

Save an entire store.

Example Request

{
    "instanceId: required": "INSTANCE_ID",
    "projectId: required": "PROJECT_ID",
    "store: required": "\"{'store': '{key1: value1, ...}'}\""
}

Example Response

{
    "msg": "Stored"
}

Upload Remote Assets¶

POST /api/rest/v2/write/experiment/assets/remote/batch

Upload remote assets

Example Request

{
    "remoteAssets": [
        {
            "artifactId": "39ea3587-991f-43f7-be44-6add8cee282c",
            "artifactVersionId": "692dd29d-086e-4dd8-852a-ed002ace1654",
            "assetId": "someAssetId",
            "fileName": "file.py",
            "link": "some.com/source?test=123",
            "metadata": "{\"some\":\"metadata\"}",
            "type": "3d-points"
        }
    ]
}

Example Response

"[response]"

Note: added 2022/02/01

Delete an Asset¶

POST /api/rest/v2/write/experiment/asset/delete?experimentKey=KEY&assetId=ID

Delete an experiment's asset

Example Response

"[response]"

Note: added 2022/02/01

Add an Asset Tag¶

POST /api/rest/v2/write/experiment/asset/tag

Add a tag to an asset

Example Request

{
    "assetId": "cctWICTpuNVmtICxj6zjlveoz",
    "experimentKey": "someExperimentKey",
    "tags": [
        "otherTag"
    ]
}

Example Response

"[response]"

Note: added 2022/02/01

Delete an Asset Tag¶

GET /api/rest/v2/write/experiment/asset/tag/delete?experimentKey=KEY&assetId=ID&tag=TAG

Delete a tag from an asset

Example Response

"[response]"

Note: added 2022/02/01

Upload a Panel¶

POST /api/rest/v2/write/template/upload

Upload a Panel to a workspace

Example Response

"[response]"

Note: added 2022/02/01

Remote Procedure Call¶

POST /api/rest/v2/write/experiment/rpc/send

Create a Remote Procedure Call (RPC) on an experiment

Example Response

"[response]"

Note: added 2022/02/01

Update Webhook Configuration¶

POST /api/webhooks/config

Update webhook configuration. The webhook notifies about any change in the Stage status of a specific registered model, or of any registered model in a specific workspace.

Example Request

{
    "webhookConfigs": [
        {
            "modelName": "some-model",
            "webhookUrls": [
                {
                    "header": {
                        "Authorization": "secret_token",
                        "Other": "other_info"
                    },
                    "url": "https://{customer-webhook-url-a}"
                }
            ],
            "workspaceName": "some-workspace"
        }
    ]
}

Example Response

"204"

Override Webhook Configuration¶

PUT /api/webhooks/config

Configure a webhook. The webhook notifies about any change in the Stage status of a specific registered model, or of any registered model in a specific workspace.

Example Request

{
    "webhookConfigs": [
        {
            "modelName": "some-model",
            "webhookUrls": [
                {
                    "header": {
                        "Authorization": "secret_token",
                        "Other": "other_info"
                    },
                    "url": "https://{customer-webhook-url-a}"
                }
            ],
            "workspaceName": "some-workspace"
        }
    ]
}

Example Response

"204"

Write Endpoints

Create Workspace¶

Create Experiment¶

Stop Experiment¶

Archive Experiment¶

Move an Experiment to another Project¶

Add Symlink to Experiment¶

Delete Experiment¶

Restore Experiment¶

Create Project¶

Delete Project¶

Update Project¶

Update notes for Project¶

Add a Project Share Link¶

Delete a Project Share Link¶

Create Registry Model¶

Promote Experiment Model to Registry Model¶

Update Registry Model Version¶

Delete Registry Model Version¶

Update Registry Model¶

Update Registry Model Notes¶

Delete Registry Model¶

Get Model Registry Count¶

Add Registry Model Version Stage¶

Remove Registry Model Version Stage¶

Send Experiment Keep-Alive Signal¶

Set Experiment Start and End Time¶

Log Other¶

Log Parameter¶

Log Metric¶

Set HTML¶

Upload Asset¶

Upload Text Sample¶

Upload Git Patch¶

Set System Details¶

Set Git Metadata¶

Log Output¶

Log Graph¶

Set Code¶

Add Tags¶

Set a Cloud Detail Item¶

Set an Experiment's File-path¶

Add GPU Metrics¶

Add RAM Metrics¶

Add CPU Metrics¶

Add Processor Load Metrics¶

Update or Insert Artifact¶

Set Artifact State¶

Save Store¶

Upload Remote Assets¶

Delete an Asset¶

Add an Asset Tag¶

Delete an Asset Tag¶

Upload a Panel¶

Remote Procedure Call¶

Update Webhook Configuration¶

Override Webhook Configuration¶