Servers API

Create, list, update, and delete monitored servers programmatically.

List Servers

GET ?resource=servers

Returns all servers in your account.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cp.pinguzo.com/api/v1/rest.php?resource=servers

Response

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": 1,
        "name": "web-01",
        "status": "active",
        "os": "Ubuntu 22.04",
        "last_seen": 1700000000,
        "created_at": 1699000000,
        "online_status": "online"
      }
    ],
    "count": 1
  }
}

Get Server

GET ?resource=servers&id={id}

Returns details for a single server by ID.

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cp.pinguzo.com/api/v1/rest.php?resource=servers&id=1"

Response

{
  "success": true,
  "data": {
    "server": {
      "id": 1,
      "name": "web-01",
      "status": "active",
      "os": "Ubuntu 22.04",
      "last_seen": 1700000000,
      "created_at": 1699000000,
      "online_status": "online"
    }
  }
}

Create Server

POST ?resource=servers

Creates a new server. Returns HTTP 201 Created on success.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Server name (1–100 characters)

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-02"}' \
  https://cp.pinguzo.com/api/v1/rest.php?resource=servers

Response (201)

{
  "success": true,
  "data": {
    "server": {
      "id": 5,
      "name": "web-02",
      "agent_key": "a1b2c3d4e5f6..."
    }
  }
}

Installing the Agent The agent_key in the response is used to install the Pinguzo monitoring agent on your server. SSH into the server you want to monitor and run the following command, replacing YOUR_AGENT_KEY with the key from the API response:

Install Command

curl -fsSL https://api.pinguzo.com/files/install-agent.sh | sudo bash -s -- --agent-key=YOUR_AGENT_KEY

The installer will automatically select the nearest edge server, install the agent, and start reporting metrics within 60 seconds. No reboot required — the agent runs via cron. For more details, see Install Pinguzo Agent.

Update Server

PUT ?resource=servers&id={id}

Updates a server's name.

Request Body

Field	Type	Required	Description
`name`	string	Yes	New server name (1–100 characters)

Example Request

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"web-server-02"}' \
  "https://cp.pinguzo.com/api/v1/rest.php?resource=servers&id=5"

Response

{
  "success": true,
  "data": { "message": "Server updated" }
}

Delete Server

DELETE ?resource=servers&id={id}

Deletes a server and all its associated incidents.

Example Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cp.pinguzo.com/api/v1/rest.php?resource=servers&id=5"

Response

{
  "success": true,
  "data": { "message": "Server deleted" }
}

Cascade delete Deleting a server also removes all incidents and notification logs associated with it.

Server Object Fields

The following fields are returned in server responses (List and Get Server):

Field	Type	Description
`id`	integer	Unique server identifier
`name`	string	Server name (as set by you)
`status`	string	Server status: `active` or `pending`
`os`	string\|null	Operating system name and version (e.g. `Ubuntu 22.04`)
`last_seen`	integer\|null	Unix timestamp of the last agent check-in. `null` if the agent has never reported.
`created_at`	integer	Unix timestamp when the server was created
`online_status`	string	Derived from `last_seen`: `online` if seen in the last 5 minutes, otherwise `offline`

Create response The Create Server (POST) response includes a different set of fields: id, name, and agent_key. The agent_key is a 64-character hex string used to install the monitoring agent on your server.

Next Steps

Monitors API — manage monitors
Incidents API — list and filter incidents
Code Examples — copy-paste snippets