Container Operations & Lifecycle

The Container Operations API provides lifecycle control for individual containers and visibility into their state transition history. Use these endpoints to start, stop, restart, pause, or resume containers, and to audit when and how container status changes occurred.

Get Container Status Logs

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

Returns a paginated list of status transition logs for a specific container, ordered by transition time by default. Useful for auditing runtime behavior, debugging unexpected restarts, and observing how long a container spent in each state.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
page	query	number	No	Page number. Default: 1
limit	query	number	No	Number of log entries per page. Default: 10
sort_by	query	string	No	Field to sort logs 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"

Request Body

This endpoint does not accept a request body.

Response

200

{
  "statusCode": 200,
  "message": "Status logs retrieved successfully",
  "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"
        }
      },
      {
        "id": "507f1f77bcf86cd799439078",
        "container_id": "507f1f77bcf86cd799439011",
        "from_status": null,
        "to_status": "stopped",
        "transition_time": "2025-01-15T09:55:12.000Z",
        "duration_ms": null,
        "triggered_by": "system",
        "metadata": null
      }
    ],
    "pagination": {
      "total": 15,
      "page": 1,
      "limit": 10,
      "totalPages": 2
    }
  }
}

400

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

401

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

403

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

404

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

SDK Example

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

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

Manage Container

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

Performs a lifecycle operation on a container. The operation path segment selects the action: start, stop, force-stop, restart, pause, or resume. State-aware operations like start and pause return a 400 OPERATION_STATE_CONFLICT when the container is already in the target state.

Parameters

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

Request Body

This endpoint does not accept a request body.

Response

200

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

400

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

401

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

403

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

404

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

500

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

SDK Example

const result = await client.api.containers.manage({
  operation: "start",
  id: "507f1f77bcf86cd799439011"
});

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

Tip

State-aware operations such as start and pause may return a 400 OPERATION_STATE_CONFLICT if the container is already in the target state. Check the container’s current status in the response before retrying, or use force-stop and restart for operations that are valid from more states.