API Reference

Base URL: http://localhost:8080

1. Base URL + Authentication

All API endpoints (except /api/v1/auth/register and /api/v1/auth/login) require authentication using a Bearer token.

Authentication Header:

Authorization: Bearer <token>

2. Error Response Format

All error responses follow this structure:

Example:

{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

Common HTTP Status Codes: | Code | Meaning | |------|---------| | 400 | Bad Request — invalid request body or parameters | | 401 | Unauthorized — missing or invalid token | | 403 | Forbidden — insufficient permissions | | 404 | Not Found — resource does not exist | | 500 | Internal Server Error |

3. Auth

POST /api/v1/auth/register

Create a new user account.

Auth Required: No

Request Body:

Response (201 Created):

Example Response:

{
  "id": 1,
  "username": "alice",
  "email": "[email protected]"
}

Example curl:

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123","email":"[email protected]"}'

POST /api/v1/auth/login

Authenticate and obtain a Bearer token.

Auth Required: No

Request Body:

Response (200 OK):

Example Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "alice",
    "email": "[email protected]"
  }
}

Example curl:

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"secret123"}'

GET /api/v1/auth/me

Get the currently authenticated user.

Auth Required: Yes

Response (200 OK):

Example Response:

{
  "id": 1,
  "username": "alice",
  "email": "[email protected]"
}

Example curl:

curl http://localhost:8080/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

4. Teams

GET /api/v1/teams

List all teams the authenticated user belongs to.

Auth Required: Yes

Response (200 OK):

Example Response:

{
  "teams": [
    {
      "id": 1,
      "name": "SRE Team",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Example curl:

curl http://localhost:8080/api/v1/teams \
  -H "Authorization: Bearer <token>"

POST /api/v1/teams

Create a new team.

Auth Required: Yes

Request Body:

Response (201 Created):

Example Response:

{
  "id": 2,
  "name": "Platform Team",
  "created_at": "2026-04-12T14:30:00Z"
}

Example curl:

curl -X POST http://localhost:8080/api/v1/teams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform Team"}'

POST /api/v1/teams/:id/inite

Initialize a team (set up team configuration or complete onboarding). The exact semantics depend on the backend implementation.

Auth Required: Yes

Path Parameters:

Request Body:

Response (200 OK):

Example Response:

{
  "id": 1,
  "name": "SRE Team",
  "initialized": true,
  "config": {}
}

Example curl:

curl -X POST http://localhost:8080/api/v1/teams/1/inite \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"config":{}}'

GET /api/v1/invitations

List all pending invitations for the authenticated user.

Auth Required: Yes

Response (200 OK):

Example Response:

{
  "invitations": [
    {
      "id": 10,
      "team_id": 1,
      "team_name": "SRE Team",
      "status": "pending",
      "created_at": "2026-04-10T08:00:00Z"
    }
  ]
}

Example curl:

curl http://localhost:8080/api/v1/invitations \
  -H "Authorization: Bearer <token>"

POST /api/v1/invitations/:id/accept

Accept a team invitation.

Auth Required: Yes

Path Parameters:

Response (200 OK):

Example Response:

{
  "message": "Invitation accepted",
  "team_id": 1
}

Example curl:

curl -X POST http://localhost:8080/api/v1/invitations/10/accept \
  -H "Authorization: Bearer <token>"

POST /api/v1/invitations/:id/decline

Decline a team invitation.

Auth Required: Yes

Path Parameters:

Response (200 OK):

Example Response:

{
  "message": "Invitation declined"
}

Example curl:

curl -X POST http://localhost:8080/api/v1/invitations/10/decline \
  -H "Authorization: Bearer <token>"

POST /api/v1/teams/:id/leave

Leave a team.

Auth Required: Yes

Path Parameters:

Response (200 OK):

Example Response:

{
  "message": "You have left the team"
}

Example curl:

curl -X POST http://localhost:8080/api/v1/teams/1/leave \
  -H "Authorization: Bearer <token>"

5. Monitor Targets

GET /api/v1/monitor-targets

List all monitor targets for the authenticated user's teams.

Auth Required: Yes

Response (200 OK):

Example Response:

{
  "monitor_targets": [
    {
      "id": 1,
      "name": "web-server-01",
      "type": "host",
      "address": "192.168.1.10",
      "team_id": 1,
      "created_at": "2026-02-01T12:00:00Z"
    }
  ]
}

Example curl:

curl http://localhost:8080/api/v1/monitor-targets \
  -H "Authorization: Bearer <token>"

POST /api/v1/monitor-targets

Create a new monitor target.

Auth Required: Yes

Request Body:

Response (201 Created):

Example Response:

{
  "id": 2,
  "name": "api-server",
  "type": "host",
  "address": "10.0.0.5",
  "team_id": 1,
  "labels": {"env": "production"},
  "created_at": "2026-04-12T15:00:00Z"
}

Example curl:

curl -X POST http://localhost:8080/api/v1/monitor-targets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"api-server","type":"host","address":"10.0.0.5","team_id":1,"labels":{"env":"production"}}'

DELETE /api/v1/monitor-targets/:id

Delete a monitor target.

Auth Required: Yes

Path Parameters:

Response (200 OK):

Example Response:

{
  "message": "Monitor target deleted"
}

Example curl:

curl -X DELETE http://localhost:8080/api/v1/monitor-targets/2 \
  -H "Authorization: Bearer <token>"

6. Alert Ingest

POST /api/v1/alerts/alertmanager/:tenant_id

Ingest alerts from Prometheus Alertmanager.

Auth Required: No (uses tenant_id for routing; optionally validate Bearer token)

Path Parameters:

Request Body (Alertmanager payload):

Response (200 OK):

Example Response:

{
  "status": "success",
  "processed": 3
}

Example curl:

curl -X POST http://localhost:8080/api/v1/alerts/alertmanager/tenant-123 \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v4",
    "groupKey": "tenant-123:alert-group-1",
    "status": "firing",
    "receiver": "lingwang",
    "alerts": [
      {
        "status": "firing",
        "labels": {"alertname": "HighCPU", "severity": "warning"},
        "annotations": {"summary": "High CPU usage detected"},
        "startsAt": "2026-04-12T10:00:00Z"
      }
    ]
  }'

POST /api/v1/alerts/zabbix/:tenant_id

Ingest alerts from Zabbix.

Auth Required: No (uses tenant_id for routing)

Path Parameters:

Request Body:

Response (200 OK):

Example Response:

{
  "status": "success",
  "processed": 1
}

Example curl:

curl -X POST http://localhost:8080/api/v1/alerts/zabbix/tenant-123 \
  -H "Content-Type: application/json" \
  -d '{
    "host": "zabbix-server-01",
    "key": "vfs.fs.size[/,pused]",
    "value": "85",
    "clock": 1712923200,
    "severity": 3,
    "tags": {"datacenter": "dc1"}
  }'

POST /api/v1/alerts/agent/:tenant_id

Ingest alerts from a lightweight monitoring agent.

Auth Required: No (uses tenant_id for routing)

Path Parameters:

Request Body:

Response (200 OK):

Example Response:

{
  "status": "success",
  "processed": 2
}

Example curl:

curl -X POST http://localhost:8080/api/v1/alerts/agent/tenant-123 \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "agent-node-01",
    "metrics": [
      {"name": "cpu_usage", "value": 78.5, "timestamp": 1712923200, "labels": {"core": "0"}},
      {"name": "memory_usage", "value": 62.1, "timestamp": 1712923200}
    ],
    "events": [
      {"type": "up", "message": "Agent connected", "timestamp": 1712923200}
    ]
  }'