Skip to content

REST API Endpoints

Complete reference for all REST API endpoints.

Base URL

https://your-chatops-instance.com/api/v1

Authentication

Most endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer your_access_token

Servers

List Servers

GET /servers
Authorization: Bearer {token}

Response: 

[
  {
    "id": "uuid",
    "name": "Production Server",
    "host": "192.168.1.100",
    "port": 22,
    "status": "online",
    "created_at": "2024-01-01T00:00:00Z"
  }
]

Create Server

POST /servers
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "New Server",
  "host": "192.168.1.101",
  "port": 22
}

Get Server

GET /servers/{id}
Authorization: Bearer {token}

Update Server

PUT /servers/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Name"
}

Delete Server

DELETE /servers/{id}
Authorization: Bearer {token}

Metrics

Get Latest Metrics

GET /metrics/{server_id}
Authorization: Bearer {token}

Response: 

{
  "server_id": "uuid",
  "cpu_percent": 45.2,
  "memory_percent": 62.5,
  "disk_usage": [
    {
      "path": "/",
      "total": 1000000000,
      "used": 500000000,
      "free": 500000000,
      "percent": 50.0
    }
  ],
  "network": [
    {
      "interface": "eth0",
      "bytes_sent": 1000000,
      "bytes_recv": 2000000
    }
  ],
  "timestamp": "2024-01-01T00:00:00Z"
}

Get Metrics History

GET /metrics/{server_id}/history?start=2024-01-01T00:00:00Z&end=2024-01-01T23:59:59Z
Authorization: Bearer {token}

Docker

List Containers

GET /docker/{server_id}/containers
Authorization: Bearer {token}

Start Container

POST /docker/{server_id}/containers/{container_id}/start
Authorization: Bearer {token}

Stop Container

POST /docker/{server_id}/containers/{container_id}/stop?timeout=10
Authorization: Bearer {token}

Restart Container

POST /docker/{server_id}/containers/{container_id}/restart?timeout=10
Authorization: Bearer {token}

Get Container Logs

GET /docker/{server_id}/containers/{container_id}/logs?tail=100
Authorization: Bearer {token}

Commands

Execute Command

POST /commands/{server_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "command": "ls -la"
}

Response: 

{
  "command_id": "uuid",
  "command": "ls -la",
  "output": "total 100\n...",
  "exit_code": 0,
  "duration_ms": 150
}

Alerts

List Alerts

GET /alerts?status=active&server_id={uuid}
Authorization: Bearer {token}

Resolve Alert

POST /alerts/{id}/resolve
Authorization: Bearer {token}

List Thresholds

GET /alerts/thresholds?server_id={uuid}
Authorization: Bearer {token}

Create Threshold

POST /alerts/thresholds
Authorization: Bearer {token}
Content-Type: application/json

{
  "server_id": "uuid",
  "metric_type": "cpu",
  "threshold_value": 80.0,
  "comparison": "gt",
  "enabled": true
}

API Keys

List My API Keys

GET /api-keys/me
Authorization: Bearer {token}

Create API Key

POST /api-keys
Authorization: Bearer {token}
Content-Type: application/json

{
  "server_id": "uuid",
  "name": "Production Agent"
}

Response: 

{
  "id": "uuid",
  "name": "Production Agent",
  "server_id": "uuid",
  "key": "chatops_xxxxxxxxxxxx",  // Only shown once!
  "created_at": "2024-01-01T00:00:00Z"
}

Revoke API Key

DELETE /api-keys/{id}
Authorization: Bearer {token}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "detail": "Invalid request"
}

401 Unauthorized

{
  "detail": "Could not validate credentials"
}

403 Forbidden

{
  "detail": "Not enough permissions"
}

404 Not Found

{
  "detail": "Resource not found"
}

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Interactive Documentation

For interactive API documentation, visit: - /docs - Swagger UI - /redoc - ReDoc

Next Steps