Container Operations & Lifecycle

This page covers the control-plane endpoints used to perform lifecycle actions on a container and to inspect the history of those actions. Use the manage endpoint to start, stop, restart, pause, or resume a container, and use the status logs endpoint to retrieve a paginated audit trail of every state transition the container has gone through.

All requests on this page are scoped to a single container, identified by its 24-character hexadecimal container ID in the URL.

Manage Container

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

Perform a lifecycle operation on a container. Supported operations include start, stop, force-stop, restart, pause, and resume.

The operation is encoded as a path segment rather than a body field, which keeps each operation idempotent and cacheable at the HTTP layer.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Container ID
operation	path	string	Yes	One of: start, stop, force-stop, restart, pause, resume

This endpoint accepts no request body.

Example Request

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

Responses

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

Get Status Logs

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

Retrieve a paginated list of status transition logs for a specific container. Each log entry records a single state transition (for example, stopped -> running), who or what triggered it, when it occurred, and how long the previous state lasted.

Use this endpoint to audit lifecycle activity, debug unexpected restarts, or render a transition timeline in a dashboard.

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 items per page (default 10)
sort_by	query	string	No	Field to sort by. One of transition_time, created_at, to_status, from_status (default transition_time)
sort_order	query	string	No	Sort direction. One of asc, desc (default desc)

This endpoint accepts no request body.

Example Request

cURL

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

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });

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

Responses

200

{
  "statusCode": 200,
  "message": "Container 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-15T10:29:55.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.

Note

The metadata field on each log entry is null for transitions that were not triggered by a recognized command, and an object (for example, { "command": "start" }) when one is available.