Create an agent

POST

agents

Create an Observer Agent and get its key (shown once) with install commands

curl --request POST \
  --url https://use.observer/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('https://use.observer/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://use.observer/api/v1/agents"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "never_connected",
    "online": true,
    "created_at": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "last_heartbeat_at": "2023-11-07T05:31:56Z",
    "version": "<string>",
    "is_demo": true,
    "first_heartbeat_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "revoked_at": "2023-11-07T05:31:56Z",
    "previous_key_valid_until": "2023-11-07T05:31:56Z",
    "metric_count": 123,
    "source_types_active": [
      "<string>"
    ],
    "queue_depth": 123,
    "otlp_stats": {},
    "custom_probes": [
      {}
    ],
    "prometheus_url": "<string>",
    "install": {
      "docker": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "compose": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "kubernetes": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "systemd": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "binary": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      }
    },
    "env": {}
  },
  "agent_key": "<string>",
  "install": {
    "docker": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "compose": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "kubernetes": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "systemd": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "binary": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    }
  },
  "env": {}
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

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.

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

The agent, without its placeholder install and env (the ones below carry the key).

Show child attributes

agent_key

string

required

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

install

object

required

Install snippets, one per target: docker (docker run), compose, kubernetes (Secret + Deployment manifest), systemd and binary. Without prometheus_url they are for a probes-only agent. The agent key is filled in.

Show child attributes

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.

Show child attributes

Create an Observer Agent and get its key (shown once) with install commands

curl --request POST \
  --url https://use.observer/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('https://use.observer/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://use.observer/api/v1/agents"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agent": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "status": "never_connected",
    "online": true,
    "created_at": "2023-11-07T05:31:56Z",
    "description": "<string>",
    "last_heartbeat_at": "2023-11-07T05:31:56Z",
    "version": "<string>",
    "is_demo": true,
    "first_heartbeat_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "revoked_at": "2023-11-07T05:31:56Z",
    "previous_key_valid_until": "2023-11-07T05:31:56Z",
    "metric_count": 123,
    "source_types_active": [
      "<string>"
    ],
    "queue_depth": 123,
    "otlp_stats": {},
    "custom_probes": [
      {}
    ],
    "prometheus_url": "<string>",
    "install": {
      "docker": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "compose": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "kubernetes": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "systemd": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      },
      "binary": {
        "label": "<string>",
        "content": "<string>",
        "file": "<string>",
        "logs_command": "<string>",
        "note": "<string>"
      }
    },
    "env": {}
  },
  "agent_key": "<string>",
  "install": {
    "docker": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "compose": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "kubernetes": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "systemd": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "binary": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    }
  },
  "env": {}
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

Getting started

Account

Status pages

Services

Metrics

SLOs

SLA statements

Incidents

Maintenances

Config as code

Agents

Change events

Authorizations

Body

Response