Container Operations & Lifecycle

Overview

The Container Operations & Lifecycle API provides endpoints for controlling the runtime state of your containers and auditing their lifecycle history. Use these endpoints to programmatically start, stop, force-stop, restart, pause, or resume containers, and to retrieve a paginated audit trail of status transitions for compliance, debugging, or observability purposes.

Manage container

Perform a lifecycle operation on a container. The desired action is passed as the operation path parameter.

`POST /api/v1/containers/{id}/{operation}`

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`operation`	path	string	Yes	Operation to perform. Allowed values: `start`, `stop`, `force-stop`, `restart`, `pause`, `resume`

This endpoint takes no request body.

curl -X POST https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/start \
  -H "Authorization: Bearer <token>"

await client.api.containers.manage("start");

{
  "statusCode": 200,
  "message": "Container operation completed successfully",
  "data": {
    "error": false,
    "operation": "start",
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "message": "Container started successfully",
    "status": "running"
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Container is already running",
  "data": {
    "error": true,
    "operation": "start",
    "container_id": "507f1f77bcf86cd799439011",
    "project_id": "507f1f77bcf86cd799439033",
    "message": "Container is already running",
    "status": "running"
  }
}

Error Code	Title	Description	Resolution
`VALIDATION_ERROR`	Invalid input parameters	One or more request parameters failed validation	Check the error message for specific field requirements and correct your input
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)
`OPERATION_STATE_CONFLICT`	Container State Conflict	The operation cannot be performed because the container is not in the correct state.	Check the container’s current status. For example, a container must be stopped to be started.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status
`OPERATION_NOT_PERMITTED_ON_EXPIRED`	Operation Not Permitted on Expired Container	This operation cannot be performed because the container has expired due to server termination.	The container is in a read-only state. No further operations are allowed. Please create a new container.

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
`CONTAINER_NOT_FOUND`	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Error Code	Title	Description	Resolution
`INTERNAL_SERVER_ERROR`	Internal server error	An unexpected error occurred on the server	Try again later, or contact support if the problem persists
`EXTERNAL_SERVICE_ERROR`	External service error	A required external service is unavailable or returned an error	Try again later when the external service is available

Get status logs

Retrieve a paginated list of status transition logs for a specific container, including the prior state, new state, the actor that triggered the change, and the time spent in the previous state.

`GET /api/v1/containers/{id}/status-logs`

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Container ID
`page`	query	number	No	Page number. Default: `1`
`limit`	query	number	No	Items per page. Default: `10`
`sort_by`	query	string	No	Field to sort by. Default: `"transition_time"`. Allowed values: `"transition_time"`, `"created_at"`, `"to_status"`, `"from_status"`
`sort_order`	query	string	No	Sort direction. Default: `"desc"`. Allowed values: `"asc"`, `"desc"`

This endpoint takes no request body.

curl -X GET "https://api.hoody.icu/api/v1/containers/507f1f77bcf86cd799439011/status-logs?page=1&limit=10&sort_by=transition_time&sort_order=desc" \
  -H "Authorization: Bearer <token>"

await client.api.containers.getStatusLogs("507f1f77bcf86cd799439011", {
  page: 1,
  limit: 10,
  sort_by: "transition_time",
  sort_order: "desc"
});

{
  "statusCode": 200,
  "message": "Successful response",
  "data": {
    "logs": [
      {
        "id": "507f1f77bcf86cd799439077",
        "container_id": "507f1f77bcf86cd799439011",
        "from_status": "stopped",
        "to_status": "running",
        "transition_time": "2025-01-15T10:30:00.000Z",
        "duration_ms": 3500,
        "triggered_by": "user",
        "metadata": {
          "command": "start"
        }
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 10,
      "totalPages": 2
    }
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid ID format"
}

Error Code	Title	Description	Resolution
`INVALID_ID_FORMAT`	Invalid ID format	The provided ID must be a 24-character hexadecimal string	Ensure the ID is exactly 24 characters long and contains only hexadecimal characters (0-9, a-f)

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Authentication token required"
}

Error Code	Title	Description	Resolution
`MISSING_TOKEN`	Authentication token missing	No authentication token was provided in the request	Include a valid JWT token in the Authorization header as `Bearer <token>`
`INVALID_TOKEN`	Invalid authentication token	The provided authentication token is malformed or invalid	Obtain a new token by logging in again or using a valid auth token
`TOKEN_EXPIRED`	Authentication token expired	The provided authentication token has expired	Obtain a new token by logging in again or refreshing your session

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Error Code	Title	Description	Resolution
`INSUFFICIENT_PERMISSIONS`	Insufficient permissions	You do not have the required permissions to perform this action	Contact the resource owner or administrator to request access
`ACCOUNT_BANNED`	Account banned	Your account has been banned and cannot access this resource	Contact support for information about your account status

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Container not found"
}

Error Code	Title	Description	Resolution
`CONTAINER_NOT_FOUND`	Container not found	The requested container does not exist or you do not have permission to access it.	Verify the container ID is correct and that you have access to the project it belongs to.