Groups

Create, rename, delete, and list tenant-scoped Paperpin groups for organizing web monitoring resources.

Base URL: https://paperpin.io/api/v1

Every request requires Authorization: Bearer pp_....

List groups

GET /groups

{
  "data": [
    {
      "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
      "name": "Production",
      "created_at": "2026-07-16T08:00:00.000Z",
      "updated_at": "2026-07-16T08:00:00.000Z"
    }
  ]
}

Get a group

GET /groups/:groupId

{
  "data": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  }
}

Returns 404 when the group is missing or belongs to another tenant.

Create a group

POST /groups

{ "name": "Production" }

The name is required and may contain up to 32 characters. A successful request returns 201; duplicate tenant group names return 409.

{
  "data": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Production",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T08:00:00.000Z"
  }
}

Rename a group

PATCH /groups/:groupId

{ "name": "Marketing" }

The response contains the updated group in data.

{
  "data": {
    "id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
    "name": "Marketing",
    "created_at": "2026-07-16T08:00:00.000Z",
    "updated_at": "2026-07-16T09:00:00.000Z"
  }
}

Delete a group

DELETE /groups/:groupId

Returns 204 No Content on success. The operation only deletes the group container; it does not expose or mutate PaperPin's private monitoring configuration.

The successful response has no JSON body.

List group monitors

GET /groups/:groupId/monitors

Returns the group's public monitor resources in data.

{
  "data": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T08:15:00.000Z"
    }
  ]
}

Add one monitor to a group

POST /groups/:groupId/monitors

{ "monitor_id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f" }

Returns the updated monitor in data.

{
  "data": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T09:00:00.000Z"
    }
  ]
}

Returns 404 when the group is missing, any monitor is missing, or any resource belongs to another tenant.

Add multiple monitors to a group

POST /groups/:groupId/monitors

{
  "monitor_ids": [
    "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
    "9f77f222-4919-404d-817f-34dca46fb221"
  ]
}

Remove one monitor from a group

DELETE /groups/:groupId/monitors

{ "monitor_id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f" }

Returns the updated monitor in data with group_id set to null.

{
  "data": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": null,
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T09:00:00.000Z"
    }
  ]
}

Returns 404 when the group is missing, the monitor is missing, the monitor is not in that group, or any resource belongs to another tenant.

Remove multiple monitors from a group

DELETE /groups/:groupId/monitors

{
  "monitor_ids": [
    "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
    "9f77f222-4919-404d-817f-34dca46fb221"
  ]
}

The request accepts up to 100 monitor IDs. If any monitor is missing, belongs to another tenant, or is not currently in the group, no removal is attempted and the response is 404.

The request accepts up to 100 monitor IDs. If any monitor ID is missing or belongs to another tenant, no assignment is attempted and the response is 404.

{
  "data": [
    {
      "id": "99b61a96-40d9-44a6-9fd5-e56e5d29e49f",
      "name": "Pricing page",
      "url": "https://example.com/pricing",
      "group_id": "0e838345-648b-46f5-8586-6e8b2f7bbf76",
      "status": "active",
      "interval_minutes": 60,
      "detection_mode": "visual",
      "sensitivity": "medium",
      "last_successful_check_at": "2026-07-16T08:15:00.000Z",
      "last_detected_change_at": null,
      "created_at": "2026-07-15T08:00:00.000Z",
      "updated_at": "2026-07-16T09:00:00.000Z"
    }
  ]
}

On this page