Skip to main content
POST
Issue a new agent 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

Path Parameters

id
string<uuid>
required

Agent id.

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
invalidate_immediately
boolean
default:false

true: the old key stops working now (a leaked key). Default: it keeps working for 24 hours so the new one can be deployed first.

Response

ok

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.