Skip to main content
POST
Create an Observer Agent and get its key (shown once)

Authorizations

Authorization
string
header
required

An organization API key (obs_pub_…) sent as Authorization: Bearer <key>. Each key carries scopes; an endpoint lists the scope it needs. read:change_events is reserved: keys can carry it, but no endpoint needs it yet.

Scopes

write:agents

Query Parameters

target
enum<string>

Add the install snippet for this one target (and env): docker, compose, kubernetes, systemd (Linux), launchd (macOS) or binary (Linux or macOS, foreground).

Available options:
docker,
compose,
kubernetes,
systemd,
launchd,
binary
include
enum<string>

install: add every install snippet (and env). Omit it for the small default response.

Available options:
install
delivery
enum<string>
default:plaintext

plaintext (default): the key is in the response. claim: the response carries no key, only claim_url, a single-use console link (15 minutes) that shows the key once to a signed-in member of the organization.

Available options:
plaintext,
claim

Body

application/json
name
string
required

Agent name. Config documents name the agent a metric runs on by this, so keep it unique in the organization (not enforced, as in the console).

Required string length: 1 - 120
description
string
Maximum string length: 500
prometheus_url
string<uri>

Prometheus base URL the agent will query, if it reads PromQL metrics. Omit for an agent that only runs probes (HTTP, TCP, DNS, database, ...).

Response

created

agent
object
required
agent_key
string
required

The agent key (obs_live_…). Returned only in this response; Observer stores a hash and cannot show it again.

env
object
required

The agent's environment as NAME: value (AGENT_KEY, CLOUD_SERVER_URL, and PROMETHEUS_SERVER_URL for a Prometheus agent), for installs the snippets do not cover, such as an existing Compose file or Helm values. The agent key is filled in.

install
object

Only with ?target= or ?include=install. Install snippets keyed by target: docker (docker run), compose, kubernetes (Secret + Deployment manifest), systemd (Linux service), launchd (macOS LaunchAgent) and binary (foreground, Linux or macOS). Only the requested target with ?target=, all of them with ?include=install. The systemd, launchd and binary snippets pick the right binary on the host (uname). Without prometheus_url they are for a probes-only agent. The agent key is filled in.

install_targets
enum<string>[]

Without ?target= / ?include=install: the targets an install snippet exists for.

Available options:
docker,
compose,
kubernetes,
systemd,
launchd,
binary
install_hint
string

Without ?target= / ?include=install: how to get the install command.