container-census/API.md

Container Census API Documentation

Base URL

http://localhost:8080/api

---

Host Endpoints

GET /hosts

List all configured hosts.

Response:

[
  {
    "id": 1,
    "name": "local",
    "address": "unix:///var/run/docker.sock",
    "description": "Local Docker daemon",
    "enabled": true,
    "created_at": "2025-10-07T14:52:58Z",
    "updated_at": "2025-10-07T14:52:58Z"
  }
]

GET /hosts/{id}

Get a specific host by ID.

POST /hosts/agent

Add a new agent-based host.

Request:

{
  "name": "production-server",
  "address": "http://192.168.1.100:9876",
  "description": "Production Docker host",
  "agent_token": "abc123def456..."
}

Response:

{
  "id": 2,
  "name": "production-server",
  "address": "http://192.168.1.100:9876",
  "description": "Production Docker host",
  "host_type": "agent",
  "agent_status": "online",
  "enabled": true
}

POST /hosts/agent/test

Test connection to an agent.

Request:

{
  "address": "http://192.168.1.100:9876",
  "agent_token": "abc123def456..."
}

Response:

{
  "success": true,
  "message": "Agent is reachable"
}

---

Container Endpoints

GET /containers

Get latest containers from all hosts.

Response:

[
  {
    "id": "abc123...",
    "name": "my-container",
    "image": "nginx:latest",
    "image_id": "sha256:...",
    "state": "running",
    "status": "Up 2 hours",
    "ports": [...],
    "labels": {...},
    "created": "2025-10-07T12:00:00Z",
    "host_id": 1,
    "host_name": "local",
    "scanned_at": "2025-10-07T14:52:58Z"
  }
]

GET /containers/host/{id}

Get latest containers for a specific host.

GET /containers/history?start={RFC3339}&end={RFC3339}

Get historical container data within a time range.

Query Parameters:

• start - Start time (RFC3339 format, defaults to 24 hours ago)
• end - End time (RFC3339 format, defaults to now)

---

Container Management Endpoints

POST /containers/{host_id}/{container_id}/start

Start a stopped container.

Response:

{
  "message": "Container started"
}

Example:

curl -X POST http://localhost:8080/api/containers/1/abc123/start

POST /containers/{host_id}/{container_id}/stop

Stop a running container.

Query Parameters:

• timeout - Timeout in seconds (default: 10)

Response:

{
  "message": "Container stopped"
}

Example:

curl -X POST "http://localhost:8080/api/containers/1/abc123/stop?timeout=30"

POST /containers/{host_id}/{container_id}/restart

Restart a container.

Query Parameters:

• timeout - Timeout in seconds (default: 10)

Response:

{
  "message": "Container restarted"
}

Example:

curl -X POST "http://localhost:8080/api/containers/1/abc123/restart?timeout=30"

DELETE /containers/{host_id}/{container_id}

Remove a container.

Query Parameters:

• force - Force removal (default: false)

Response:

{
  "message": "Container removed"
}

Example:

# Remove stopped container
curl -X DELETE http://localhost:8080/api/containers/1/abc123

# Force remove running container
curl -X DELETE "http://localhost:8080/api/containers/1/abc123?force=true"

GET /containers/{host_id}/{container_id}/logs

Get container logs.

Query Parameters:

• tail - Number of lines to retrieve (default: 100)

Response:

{
  "logs": "2025-10-07 14:52:58 Starting application...\n..."
}

Example:

# Get last 50 lines
curl "http://localhost:8080/api/containers/1/abc123/logs?tail=50"

---

Image Endpoints

GET /images

List all images from all hosts.

Response:

{
  "local": {
    "host_id": 1,
    "images": [
      {
        "Id": "sha256:...",
        "RepoTags": ["nginx:latest"],
        "Created": 1696723200,
        "Size": 142000000,
        "VirtualSize": 142000000,
        "Containers": 2
      }
    ]
  }
}

GET /images/host/{id}

List all images for a specific host.

Response:

[
  {
    "Id": "sha256:...",
    "RepoTags": ["nginx:latest"],
    "Created": 1696723200,
    "Size": 142000000,
    "VirtualSize": 142000000,
    "Containers": 2
  }
]

DELETE /images/{host_id}/{image_id}

Remove an image.

Query Parameters:

• force - Force removal (default: false)

Response:

{
  "message": "Image removed"
}

Example:

# Remove unused image
curl -X DELETE http://localhost:8080/api/images/1/sha256:abc123...

# Force remove image (even if containers are using it)
curl -X DELETE "http://localhost:8080/api/images/1/sha256:abc123...?force=true"

POST /images/host/{id}/prune

Remove all unused images from a host.

Response:

{
  "message": "Images pruned",
  "space_reclaimed": 524288000
}

Example:

curl -X POST http://localhost:8080/api/images/host/1/prune

---

Scan Endpoints

POST /scan

Trigger a manual scan of all hosts.

Response:

{
  "message": "Scan triggered"
}

GET /scan/results?limit={N}

Get recent scan results.

Query Parameters:

• limit - Number of results to return (default: 50)

Response:

[
  {
    "id": 1,
    "host_id": 1,
    "host_name": "local",
    "started_at": "2025-10-07T14:52:58Z",
    "completed_at": "2025-10-07T14:52:59Z",
    "success": true,
    "error": "",
    "containers_found": 10
  }
]

---

Health Endpoint

GET /health

Health check endpoint.

Response:

{
  "status": "healthy",
  "time": "2025-10-07T14:52:58Z"
}

---

Error Responses

All endpoints return standard error responses:

{
  "error": "Error message describing what went wrong"
}

Common HTTP Status Codes:

• 200 OK - Success
• 202 Accepted - Request accepted (async operations)
• 400 Bad Request - Invalid input
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

---

Examples

Start a Container

curl -X POST http://localhost:8080/api/containers/1/abc123/start

Stop Multiple Containers (using a script)

#!/bin/bash
HOST_ID=1
for CONTAINER_ID in $(curl -s http://localhost:8080/api/containers | jq -r '.[] | select(.state=="running") | .id'); do
  curl -X POST "http://localhost:8080/api/containers/$HOST_ID/$CONTAINER_ID/stop"
done

Clean Up Unused Images

curl -X POST http://localhost:8080/api/images/host/1/prune

Monitor Container Logs

# Get logs for a specific container
curl -s "http://localhost:8080/api/containers/1/abc123/logs?tail=100"