[← Back to index](./index.md)

# Private Location Service

Manage private locations — self-hosted checker agents that run your monitors
from inside your own network, instead of from OpenStatus' public regions. The
Private Location Service provides 5 RPC methods.

Each private location owns an **agent token**, generated by the server on
creation. The agent uses it to authenticate, so treat it as a secret: it is
returned by `createPrivateLocation` and `getPrivateLocation`, and deliberately
omitted from `listPrivateLocations`.

All examples assume you have created a client:

```typescript
import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});
```

## Create Private Location

```typescript
const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.createPrivateLocation({
    name: "eu-datacenter",
    monitorIds: ["123456"], // optional
    metadata: { env: "production", team: "platform" }, // optional
  });

console.log(`ID: ${privateLocation?.id}`);
console.log(`Token: ${privateLocation?.token}`); // store securely
```

### Create Options

| Option       | Type                   | Required | Description                           |
| ------------ | ---------------------- | -------- | ------------------------------------- |
| `name`       | string                 | Yes      | Display name for the private location |
| `monitorIds` | string[]               | No       | Monitors this location runs           |
| `metadata`   | Record<string, string> | No       | User-defined key/value labels         |

## Get Private Location

Returns the full private location, including its agent token.

```typescript
import { PrivateLocationStatus } from "@openstatus/sdk-node";

const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.getPrivateLocation({ id: "pl_123" });

if (privateLocation) {
  console.log(`Name:      ${privateLocation.name}`);
  console.log(`Status:    ${PrivateLocationStatus[privateLocation.status]}`);
  console.log(`Monitors:  ${privateLocation.monitorIds.join(", ")}`);
  console.log(`Last seen: ${privateLocation.lastSeenAt || "never"}`);
}
```

`status` is computed from the agent heartbeat and is read-only: `ACTIVE` means
the agent is reporting normally, `ERROR` means it has stopped reporting. See
[PrivateLocationStatus](./reference.md#privatelocationstatus).

## List Private Locations

Returns `PrivateLocationSummary` values — the agent token is **not** included.

```typescript
const { privateLocations, totalSize } = await client.privateLocation.v1
  .PrivateLocationService.listPrivateLocations({ limit: 10, offset: 0 });

console.log(`Found ${totalSize} private locations`);
for (const location of privateLocations) {
  console.log(
    `  ${location.name}: ${location.monitorCount} monitors, ` +
      `last seen ${location.lastSeenAt || "never"}`,
  );
}
```

| Option   | Type   | Required | Description                       |
| -------- | ------ | -------- | --------------------------------- |
| `limit`  | number | No       | Page size (1–100)                 |
| `offset` | number | No       | Number of results to skip (min 0) |

## Update Private Location

```typescript
const { privateLocation } = await client.privateLocation.v1
  .PrivateLocationService.updatePrivateLocation({
    id: "pl_123",
    name: "eu-datacenter-2",
    monitorIds: ["123456", "123457"],
    metadata: { env: "production" },
  });
```

## Delete Private Location

```typescript
const { success } = await client.privateLocation.v1.PrivateLocationService
  .deletePrivateLocation({ id: "pl_123" });
```

## Assigning Monitors

Monitors are attached to a private location through `monitorIds` on
`createPrivateLocation` / `updatePrivateLocation`. The relationship is also
visible from the monitor side: HTTP, TCP, and DNS monitors expose a read-only
`privateLocationIds: string[]`.

```typescript
const { httpMonitors } = await client.monitor.v1.MonitorService.listMonitors(
  {},
);

for (const monitor of httpMonitors) {
  if (monitor.privateLocationIds.length > 0) {
    console.log(`${monitor.name} → ${monitor.privateLocationIds.join(", ")}`);
  }
}
```