Uptinio Documentation

                                                                                                                                                                                                # Servers API Reference

This guide provides detailed information about the Servers API endpoints.

Metrics behavior: List and Get Server Details return only last_metrics (latest snapshot). For time-series metrics (e.g. for charts), use Get Server Metrics (GET /api/v1/servers/:uuid/metrics) with optional time range and filters.

Authentication

All server endpoints support authentication using either a Project API Token or a User Authentication Token. Include your token in the Authorization header:

bash

Authorization: Bearer YOUR_PROJECT_API_TOKEN
# or
Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN

When using a User Authentication Token, the API will automatically use the user's current project or root project.

For more information about authentication, see the Authentication Guide.

List Servers

Retrieve a list of all servers in your project. Supports pagination. Each server includes last_metrics (latest snapshot) only; time-series metrics are not returned. Use Get Server Metrics for time-range metrics.

http

GET /api/v1/servers
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Query Parameters

Parameter	Type	Description	Required
page	integer	Page number for pagination (default: 1)	No
per_page	integer	Number of servers per page	No

Example with curl (Project Token):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Example with curl (User Token):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Example with pagination:

bash

curl -X GET "https://api.uptinio.com/api/v1/servers?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[
  {
    "uuid": "SRV123",
    "hostname": "web-server-01",
    "public_ip": "192.168.1.100",
    "private_ip": "172.29.183.12",
    "mac_address": "10:e2:d2:76:ed:d8",
    "cpu_cores": 8,
    "cpu_model": "AMD Ryzen 7 3700X 8-Core Processor",
    "operating_system": "Ubuntu 22.04 LTS",
    "uptime": 2171049,
    "kernel_version": "5.19.78-generic",
    "status": "online",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z",
    "last_seen_at": "2024-01-20T14:22:00Z",
    "last_metrics": {
      "metrics": {
        "cpu_used": 24330,
        "mem_used_b": 12369505812,
        "disk_used_b": 327491256320,
        "net_recv_b": 151445,
        "net_sent_b": 102525
      },
      "timestamp": "2024-01-20T14:22:00Z"
    },
    "alert_settings": {
      "threshold": { "cpu": 90.0, "ram": 90.0, "disk": 85.0, "net_in": 10, "net_out": 10 },
      "grace_period": { "cpu": 5, "ram": 5, "disk": 10, "net_in": 3, "net_out": 3, "downtime": 5 },
      "general": { "downtime": true }
    }
  },
  {
    "uuid": "SRV456",
    "hostname": "db-server-01",
    "public_ip": "192.168.1.101",
    "private_ip": "172.29.183.13",
    "mac_address": "10:e2:d2:76:ed:d9",
    "cpu_cores": 4,
    "cpu_model": "Intel Xeon E5-2680",
    "operating_system": "Debian 12",
    "uptime": 86400,
    "kernel_version": "6.1.0-21-amd64",
    "status": "online",
    "created_at": "2024-01-16T09:15:00Z",
    "updated_at": "2024-01-20T14:21:00Z",
    "last_seen_at": "2024-01-20T14:21:00Z",
    "last_metrics": {
      "metrics": {
        "cpu_used": 18200,
        "mem_used_b": 8589934592
      },
      "timestamp": "2024-01-20T14:21:00Z"
    },
    "alert_settings": {
      "threshold": { "cpu": 90.0, "ram": 90.0, "disk": 85.0, "net_in": 10, "net_out": 10 },
      "grace_period": { "cpu": 5, "ram": 5, "disk": 10, "net_in": 3, "net_out": 3, "downtime": 5 },
      "general": { "downtime": true }
    }
  }
]

Response Fields

Field	Type	Description
uuid	string	Unique identifier for the server
hostname	string	Server hostname
public_ip	string	Public IP address of the server
private_ip	string	Private/LAN IP address of the server
mac_address	string	MAC address of the primary network interface
cpu_cores	integer	Number of CPU cores
cpu_model	string	CPU model name
operating_system	string	Operating system name and version
uptime	integer	System uptime in seconds
kernel_version	string	Kernel version string
status	string	Server status (e.g., "online", "offline")
created_at	string	ISO 8601 timestamp when the server was created
updated_at	string	ISO 8601 timestamp when the server was last updated
last_seen_at	string	ISO 8601 timestamp of the last received metrics
last_metrics	object	Latest metrics snapshot: `metrics` (key-value of metric names to raw values) and `timestamp` (ISO 8601). Omitted or empty if no metrics received yet
alert_settings	object	Alert configuration: `threshold` (cpu %, ram %, disk %, net_in/net_out MB/s), `grace_period` (minutes per metric and downtime), `general.downtime` (boolean). Values are merged with defaults; only overrides are stored

List responses do not include time-series server_metrics; use Get Server Metrics for that.

Get Server Details

Retrieve a single server's details: attributes and last_metrics (latest snapshot) only. Time-series metrics are not returned; use Get Server Metrics for that.

http

GET /api/v1/servers/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl (Project Token):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Example with curl (User Token):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "uuid": "SRV123",
  "hostname": "web-server-01",
  "public_ip": "192.168.1.100",
  "private_ip": "172.29.183.12",
  "mac_address": "10:e2:d2:76:ed:d8",
  "cpu_cores": 8,
  "cpu_model": "AMD Ryzen 7 3700X 8-Core Processor",
  "operating_system": "Ubuntu 22.04 LTS",
  "uptime": 2171049,
  "kernel_version": "5.19.78-generic",
  "status": "online",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "last_seen_at": "2024-01-20T14:22:00Z",
  "last_metrics": {
    "metrics": {
      "cpu_used": 24330,
      "mem_used_b": 12369505812,
      "disk_used_b": 327491256320,
      "net_recv_b": 151445,
      "net_sent_b": 102525
    },
    "timestamp": "2024-01-20T14:22:00Z"
  },
  "alert_settings": {
    "threshold": { "cpu": 90.0, "ram": 90.0, "disk": 85.0, "net_in": 10, "net_out": 10 },
    "grace_period": { "cpu": 5, "ram": 5, "disk": 10, "net_in": 3, "net_out": 3, "downtime": 5 },
    "general": { "downtime": true }
  }
}

Response Fields

Field	Type	Description
uuid	string	Unique identifier for the server
hostname	string	Server hostname
public_ip	string	Public IP address of the server
private_ip	string	Private/LAN IP address of the server
mac_address	string	MAC address of the primary network interface
cpu_cores	integer	Number of CPU cores
cpu_model	string	CPU model name
operating_system	string	Operating system name and version
uptime	integer	System uptime in seconds
kernel_version	string	Kernel version string
status	string	Server status (e.g., "online", "offline")
created_at	string	ISO 8601 timestamp when the server was created
updated_at	string	ISO 8601 timestamp when the server was last updated
last_seen_at	string	ISO 8601 timestamp of the last received metrics
last_metrics	object	Latest metrics snapshot: `metrics` (key-value of metric names to raw values, e.g. `cpu_used`, `mem_used_b`, `disk_used_b`) and `timestamp` (ISO 8601). Omitted or empty if no metrics received yet
alert_settings	object	Alert configuration: `threshold` (cpu %, ram %, disk %, net_in/net_out MB/s), `grace_period` (minutes per metric and downtime), `general.downtime` (boolean). Response always includes full structure (defaults merged with overrides)

Update Server

Update a server's settings. Currently only alert_settings can be updated via the API. You can send the full alert_settings object or only the keys you want to change; missing keys are left unchanged.

http

PATCH /api/v1/servers/:uuid
PUT /api/v1/servers/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Request body

Parameter	Type	Description	Required
server	object	Server payload	Yes
server.alert_settings	object	Alert configuration. Partial updates supported; only provided keys are updated	No
server.alert_settings.threshold	object	Thresholds: `cpu`, `ram`, `disk` (%), `net_in`, `net_out` (MB/s). Numbers	No
server.alert_settings.grace_period	object	Grace period in minutes: `cpu`, `ram`, `disk`, `net_in`, `net_out`, `downtime`. Integers	No
server.alert_settings.general	object	`downtime` (boolean) — enable/disable downtime notifications	No

Example — update thresholds and disable downtime notifications:

bash

curl -X PATCH "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "alert_settings": {
        "threshold": { "cpu": 80.0, "ram": 85.0 },
        "general": { "downtime": false }
      }
    }
  }'

Example — update grace periods only:

bash

curl -X PATCH "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "alert_settings": {
        "grace_period": { "cpu": 10, "downtime": 5 }
      }
    }
  }'

Response

Returns 200 OK with the full server object (same shape as Get Server Details), including the updated alert_settings.

Error Responses (Update Server)

422 Unprocessable Entity — Validation errors (e.g. invalid alert_settings).

json

{
  "errors": ["Validation error message"]
}

Get Server Metrics (time range)

Returns all server metrics within a given time range for a specific server, grouped by metric type (e.g. cpu, ram, disk) with each group ordered by timestamp. Use this endpoint when you need time-series metrics (e.g. for charts) without full server details.

http

GET /api/v1/servers/:uuid/metrics
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Query Parameters

Parameter	Type	Description	Required
since	string	ISO 8601 timestamp — only return metrics on or after this time. If both since and until are omitted, defaults to last hour	No
until	string	ISO 8601 timestamp — only return metrics on or before this time. If both since and until are omitted, defaults to now	No
metrics	string	Comma-separated list of metric names to filter. Use friendly names cpu, ram, disk, net_in, net_out (response keys match), or stored names cpu_used, mem_used_b, disk_used_b, net_recv_b, net_sent_b	No
per_page	integer	Maximum number of metric points to return (default: 10000, max: 50000). Results are then grouped by type	No

Example

Last hour (omit since and until):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123/metrics" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Custom time range:

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123/metrics?since=2024-01-20T00:00:00Z&until=2024-01-20T23:59:59Z" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

With metric filter and limit:

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123/metrics?since=2024-01-20T00:00:00Z&until=2024-01-20T23:59:59Z&metrics=cpu,ram&per_page=5000" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN"

Response

Metrics are grouped by type (cpu, ram, disk, etc.); each group is an array of points ordered by timestamp (oldest first).

json

{
  "server_uuid": "SRV123",
  "since": "2024-01-20T00:00:00Z",
  "until": "2024-01-20T23:59:59Z",
  "metrics": {
    "cpu": [
      { "value": 45.5, "timestamp": "2024-01-20T14:20:00Z" },
      { "value": 46.2, "timestamp": "2024-01-20T14:25:00Z" }
    ],
    "ram": [
      { "value": 62.3, "timestamp": "2024-01-20T14:20:00Z" },
      { "value": 63.1, "timestamp": "2024-01-20T14:25:00Z" }
    ]
  },
  "meta": {
    "total_count": 4,
    "limit": 10000,
    "metric_types": ["cpu", "ram"]
  }
}

Response Fields

Field	Type	Description
server_uuid	string	Server UUID
since	string	Requested start of time range (ISO 8601)
until	string	Requested end of time range (ISO 8601)
metrics	object	Keys are metric types (e.g. cpu, ram, disk). Each value is an array of `{ value, timestamp }` ordered by timestamp (ascending)
meta	object	`total_count` (number of points returned), `limit` (max points applied), `metric_types` (list of metric type keys)

Error Responses (metrics endpoint)

422 Unprocessable Entity — Only one of since or until provided (both required if either is set), invalid date format, or until before since.

json

{
  "error": "Provide both since and until, or omit both to use the last hour"
}

Server Integrations

You can attach integrations (e.g. webhooks, Slack, email) to a server so that alerts for that server are sent through those channels. Use the endpoints below to list, attach, and detach integrations for a server.

List Server Integrations

Get all integrations currently attached to a server.

http

GET /api/v1/servers/:uuid/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl (Project Token):

bash

curl -X GET "https://api.uptinio.com/api/v1/servers/SRV123/integrations" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN"

Example with curl (ProjectToken, local):

bash

curl http://localhost/api/v1/servers/<SERVER_UUID>/integrations \
  -H "Authorization: Bearer $ProjectToken"

Response

Returns an array of integration objects (same shape as List Integrations).

json

[
  {
    "uuid": "INT456",
    "type": "Integrations::WebhookIntegration",
    "name": "Slack Webhook",
    "settings": { "webhook_url": "https://hooks.slack.com/..." },
    "editable": true,
    "deletable": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

Attach Integration to Server

Attach an existing integration to a server. The integration will receive alerts for this server.

http

POST /api/v1/servers/:uuid/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Request body

Parameter	Type	Description	Required
integration_id	string	UUID of the integration to attach	Yes

Example with curl (Project Token):

bash

curl -X POST "https://api.uptinio.com/api/v1/servers/SRV123/integrations" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integration_id": "INT456"}'

Example with curl (ProjectToken, local):

bash

curl -X POST http://localhost/api/v1/servers/<SERVER_UUID>/integrations \
  -H "Authorization: Bearer $ProjectToken" \
  -H "Content-Type: application/json" \
  -d '{"integration_id": "<INTEGRATION_UUID>"}'

Response (attach)

Returns 201 Created with the attached integration:

json

{
  "message": "Integration attached to server",
  "integration": {
    "uuid": "INT456",
    "type": "Integrations::WebhookIntegration",
    "name": "Slack Webhook",
    "settings": { "webhook_url": "https://hooks.slack.com/..." },
    "editable": true,
    "deletable": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

If the integration is already attached, the same success response is returned (idempotent).

Detach Integration from Server

Remove an integration from a server. Alerts for this server will no longer be sent to that integration.

http

DELETE /api/v1/servers/:uuid/integrations/:integration_id
Authorization: Bearer YOUR_PROJECT_API_TOKEN

:integration_id is the integration’s UUID.

Example with curl (Project Token):

bash

curl -X DELETE "https://api.uptinio.com/api/v1/servers/SRV123/integrations/INT456" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN"

Example with curl (ProjectToken, local):

bash

curl -X DELETE http://localhost/api/v1/servers/<SERVER_UUID>/integrations/<INTEGRATION_UUID> \
  -H "Authorization: Bearer $ProjectToken"

Response (detach)

Returns 204 No Content on success. Returns 404 Not Found if the integration is not attached to this server.

Delete Server

Delete a server from your project.

http

DELETE /api/v1/servers/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl (Project Token):

bash

curl -X DELETE "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN"

Example with curl (User Token):

bash

curl -X DELETE "https://api.uptinio.com/api/v1/servers/SRV123" \
  -H "Authorization: Bearer YOUR_USER_AUTHENTICATION_TOKEN"

Response

Returns 204 No Content on successful deletion.

Error Responses

401 Unauthorized

Returned when the API token is missing or invalid.

json

{
  "error": "Unauthorized"
}

404 Not Found

Returned when the server with the specified UUID does not exist or does not belong to your project.

json

{
  "error": "Not Found"
}

422 Unprocessable Entity

Returned when there are validation errors or invalid parameters.

json

{
  "errors": [
    "Invalid metric name",
    "Invalid date format"
  ]
}

Server Metrics API - Submit server metrics
Integrations API - Create and manage integrations; attach them to servers via the endpoints above

Notes

Metrics in responses: List Servers and Get Server Details return only last_metrics (the latest snapshot per server). For time-series data (e.g. for charts), use Get Server Metrics with optional since, until, and metrics query parameters.
Servers are automatically created when metrics are submitted via the Server Metrics API if they don't already exist.
The last_seen_at and last_metrics fields are updated automatically when new metrics are received; last_metrics contains the most recent raw snapshot (e.g. cpu_used, mem_used_b, disk_used_b).
On the metrics endpoint, filtering by metric name and time range can be combined; omit both since and until to use the last hour.
All timestamps are in ISO 8601 format (UTC).

Authentication ​

List Servers ​

Query Parameters ​

Response ​

Response Fields ​

Get Server Details ​

Response ​

Response Fields ​

Update Server ​

Request body ​

Response ​

Error Responses (Update Server) ​

Get Server Metrics (time range) ​

Query Parameters ​

Example ​

Response ​

Response Fields ​

Error Responses (metrics endpoint) ​

Server Integrations ​

List Server Integrations ​

Response ​

Attach Integration to Server ​

Response (attach) ​

Detach Integration from Server ​

Response (detach) ​

Delete Server ​

Response ​

Error Responses ​

401 Unauthorized ​

404 Not Found ​

422 Unprocessable Entity ​

Related Endpoints ​

Notes ​

Authentication

List Servers

Query Parameters

Response

Response Fields

Get Server Details

Response

Response Fields

Update Server

Request body

Response

Error Responses (Update Server)

Get Server Metrics (time range)

Query Parameters

Example

Response

Response Fields

Error Responses (metrics endpoint)

Server Integrations

List Server Integrations

Response

Attach Integration to Server

Response (attach)

Detach Integration from Server

Response (detach)

Delete Server

Response

Error Responses

401 Unauthorized

404 Not Found

422 Unprocessable Entity

Related Endpoints

Notes