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

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

Example Response json { "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

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

Example Response json { "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 json { "msg": "Stop Requested" }

Archive Experiment

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

Archive an experiment.

Example Response json { "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

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

Example Response json "[response]" Note: added 2022/02/01

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

Add a symlink to an experiment.

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

Delete Experiment

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

Delete an experiment.

Example Response json { "msg": "Deleted" }

Restore Experiment

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

Restore an experiment.

Example Response json { "msg": "Restore" }

Create Project

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

Create a project.

Example Request

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

Example Response json { "projectId": "someProjectId" }

Delete Project

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

Delete a project.

Example Request

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

Example Response json { "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

json { "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 json { "msg": "Updated" }

Update notes for Project

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

Update the notes for a project.

Example Request

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

Example Response json { "msg": "Saved" }

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

Add a share-link to a project

Example Response json { "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 json "[response]" Note: added 2022/02/01

Create Registry Model

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

Create a new Registry Model.

Example Request

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

Example Response json { "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

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

Example Response json { "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

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

Example Response json "200 Ok"

Delete Registry Model Version

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

Delete a Registry Model version.

Example Response json "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

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

Example Response json "200 Ok"

Update Registry Model Notes

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

Update the notes for a Registry Model.

Example Request

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

Example Response json "200 Ok"

Delete Registry Model

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

Delete a Registry Model

Example Response json "200 Ok"

Get Model Registry Count

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

Get Model Registry count

Example Response json { "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 json "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 json "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 json { "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

json { "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 json { "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

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

Example Response json { "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

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

Example Response json { "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

json { "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 json { "msg": "Saved" }

Set HTML

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

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

Example Request

json { "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 json { "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 json { "msg": "Saved" }

Upload Text Sample

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

Upload a text sample.

Example Request

json { "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 json { "msg": "Saved" }

Upload Git Patch

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

Upload a git patch for this experiment.

Example Response json { "msg": "Saved" }

Set System Details

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

Set some or all of the system details.

Example Request

json { "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 json { "msg": "Saved" }

Set Git Metadata

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

Set an experiment's git metadata.

Example Request

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

Example Response json { "msg": "Saved" }

Log Output

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

Log a line of standard output or standard error.

Example Request

json { "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 json { "msg": "Saved" }

Log Graph

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

Log an experiment's associated model graph.

Example Request

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

Example Response json { "msg": "Saved" }

Set Code

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

Set an experiment's associated source code.

Example Request

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

Example Response json { "msg": "Saved" }

Add Tags

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

Add a list of tags to an experiment.

Example Request

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

Example Response json { "msg": "Saved" }

Set a Cloud Detail Item

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

Set one of the cloud detail items

Example Request

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

Example Response json "[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

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

Example Response json "[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

json { "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 json { "msg": "Saved" }

Add RAM Metrics

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

Add an instance of RAM usage metrics.

Example Request

json { "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 json { "msg": "Saved" }

Add CPU Metrics

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

Add an instance of CPU usage metrics.

Example Request

json { "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 json { "msg": "Saved" }

Add Processor Load Metrics

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

Add an instance of processor load metrics.

Example Request

json { "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 json { "msg": "Saved" }

Update or Insert Artifact

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

Update an existing artifact or insert a new artifact

Example Request

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

Example Response json "[response]" Note: added 2022/02/01

Set Artifact State

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

Set the state of an artifact

Example Request

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

Example Response json "[response]" Note: added 2022/02/01

Save Store

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

Save an entire store.

Example Request

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

Example Response json { "msg": "Stored" }

Upload Remote Assets

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

Upload remote assets

Example Request

json { "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 json "[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 json "[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

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

Example Response json "[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 json "[response]" Note: added 2022/02/01

Upload a Panel

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

Upload a Panel to a workspace

Example Response json "[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 json "[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

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

Example Response json "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

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

Example Response json "204"