Skip to main content

Start Clore Agent on a Machine

Endpoint Description​

POST /clore/v1/machines/agents/start

This endpoint initiates the Clore Agent on a specified machine. It requires authentication. The request must include the machine ID and the selected machine price ID to ensure the price integrity from the time of selection to deployment.

Request Body Description​

The request body for starting the Clore Agent must be a JSON object containing the following fields:

Fields​

  • machine_id: string

    • The unique identifier for the machine.

  • machine_price_id: string

    • The unique identifier for the selected price plan. This ensures that the price remains consistent even if the machine owner updates it after selection.

  • metadata: map<string, string>

    • Additional metadata required for the deployment, represented as key-value pairs.

Example Request Body​

{
  "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
  "machine_price_id": "5b10ce4d-9772-4487-bcc0-c7440e633370",
  "metadata": {
    "example_key": "example_value"
  }
}

Success Response​

Status Code: 200 OK

Response Body Description​

The response body contains information about the deployment and task initiated by starting the Clore Agent.

Fields​

  • deployment_id: string

    • The unique identifier for the deployment.

  • task_id: string

    • The unique identifier for the task associated with starting the Clore Agent.

Example Response Body​

{
  "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
  "task_id": "w1x2y3z4-5678-90ab-cdef-ghijklmnopqr"
}

HTTP Status Codes​

The "Start Clore Agent" endpoint may return the following HTTP status codes based on the outcome of the request:

  • 200 OK: The request was successful, and the response body contains the deployment and task identifiers.
  • 400 Bad Request: The server could not understand the request due to invalid syntax. This status is typically returned if required fields are missing or incorrectly formatted.
  • 401 Unauthorized: The request lacks valid authentication credentials for the target resource. This status indicates that the client must authenticate themselves to get the requested response.
  • 403 Forbidden: The server understood the request but refuses to authorize it. This typically means the requester doesn't have the required roles to access the resource.
  • 404 Not Found: The requested resource could not be found. This status may be returned if the machine ID or price ID is incorrect.
  • 500 Internal Server Error: The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no specific message is suitable.

Example cURL Request​

curl -X POST "https://api.hiveon.ai/clore/v1/machines/agents/start" \
     -H "Content-Type: application/json" \
     -d '{
           "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
           "machine_price_id": "5b10ce4d-9772-4487-bcc0-c7440e633370",
           "metadata": {
             "example_key": "example_value"
           }
         }'

This cURL command initiates the Clore Agent on a specified machine, using the provided machine ID, machine price ID, and additional metadata.