tatlock-ui/docs/CORE_API_SPEC.md

Core API Specification

Expected API endpoints for the Tatlock UI Control Room feature.

Base URL: http://{host}:8083 (configurable via CORE_API_URL)

---

Containers

List Containers

GET /infrastructure/containers

Query Parameters:

Parameter	Type	Default	Description
all	boolean	true	Include stopped containers

Response: 200 OK

[
  {
    "Id": "abc123def456...",
    "Names": ["/container-name"],
    "Image": "nginx:latest",
    "State": "running",
    "Status": "Up 2 hours",
    "Labels": {
      "com.docker.compose.project": "my-stack",
      "com.docker.compose.service": "web"
    },
    "Ports": [
      {
        "IP": "0.0.0.0",
        "PrivatePort": 80,
        "PublicPort": 8080,
        "Type": "tcp"
      }
    ],
    "Mounts": [
      {
        "Type": "bind",
        "Source": "/host/path",
        "Destination": "/container/path",
        "Mode": "rw",
        "RW": true
      }
    ],
    "NetworkSettings": {
      "Networks": {
        "bridge": {}
      }
    },
    "Created": 1704067200,
    "SizeRw": 12345,
    "SizeRootFs": 67890
  }
]

---

Get Container

GET /infrastructure/containers/{id}

Path Parameters:

Parameter	Type	Description
id	string	Full container ID

Response: 200 OK

{
  "Id": "abc123def456...",
  "Names": ["/container-name"],
  "Image": "nginx:latest",
  "State": "running",
  "Status": "Up 2 hours",
  "Labels": {},
  "Ports": [],
  "Mounts": [],
  "NetworkSettings": {},
  "Created": 1704067200
}

---

Container Actions

POST /infrastructure/containers/{id}/{action}

Path Parameters:

Parameter	Type	Description
id	string	Full container ID
action	string	One of: start, stop, restart

Response: 204 No Content

---

Get Container Logs

GET /infrastructure/containers/{id}/logs

Path Parameters:

Parameter	Type	Description
id	string	Full container ID

Query Parameters:

Parameter	Type	Default	Description
tail	integer	(all)	Number of lines from end
timestamps	boolean	false	Include timestamps

Response: 200 OK

Content-Type: text/plain

2024-01-01T12:00:00Z Log line 1
2024-01-01T12:00:01Z Log line 2
...

---

Delete Container

DELETE /infrastructure/containers/{id}

Path Parameters:

Parameter	Type	Description
id	string	Full container ID

Query Parameters:

Parameter	Type	Default	Description
force	boolean	false	Force remove running container

Response: 204 No Content

---

Stacks

Stacks are Docker Compose projects. The stack ID is the value of the com.docker.compose.project label on containers.

Get Stack Compose YAML

GET /infrastructure/stacks/{stackId}/compose

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Response: 200 OK

Content-Type: text/yaml

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  db:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}

---

Update Stack Compose YAML

PUT /infrastructure/stacks/{stackId}/compose

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Request Body:

Content-Type: text/yaml

version: '3.8'
services:
  web:
    image: nginx:latest
    ...

Response: 204 No Content

---

Get Stack Environment Variables

GET /infrastructure/stacks/{stackId}/env

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Response: 200 OK

{
  "DB_PASSWORD": "secret123",
  "API_KEY": "abc-def-ghi",
  "DEBUG": "false"
}

---

Update Stack Environment Variables

PUT /infrastructure/stacks/{stackId}/env

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Request Body:

{
  "DB_PASSWORD": "new-secret",
  "API_KEY": "new-key",
  "DEBUG": "true"
}

Response: 204 No Content

---

Deploy Stack

Redeploys the stack with current YAML and environment variables.

POST /infrastructure/stacks/{stackId}/deploy

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Response: 202 Accepted

---

Rebuild Stack

Pulls fresh images and recreates all containers in the stack.

POST /infrastructure/stacks/{stackId}/rebuild

Path Parameters:

Parameter	Type	Description
stackId	string	Stack name (compose project name)

Response: 202 Accepted

---

Data Types Reference

Container States

Value	Description
created	Container created but not started
running	Container is running
paused	Container is paused
restarting	Container is restarting
removing	Container is being removed
exited	Container has exited
dead	Container is dead

Port Types

Value	Description
tcp	TCP port
udp	UDP port

Mount Types

Value	Description
bind	Bind mount from host
volume	Docker volume
tmpfs	Temporary filesystem

---

Error Responses

All endpoints return standard HTTP error codes:

Code	Description
400	Bad Request - Invalid parameters
404	Not Found - Container/Stack not found
409	Conflict - Container already in requested state
500	Internal Server Error

Error Body:

{
  "error": "Container not found",
  "code": "NOT_FOUND"
}