Config as code

Apply config

Validates the whole document, then upserts the services, metrics, SLOs and pages it names. Use ?dryRun=true to get the diff without changing anything (run it on pull requests); ?prune=true also deletes config-managed objects absent from the document. The body is YAML (text/yaml or text/plain) or JSON, at most 1 MB.

Top-level keys other than apiVersion, metrics, services and pages are ignored and reported in warnings (for example incidents, which are managed through the API). Warnings never block an apply.

A metric’s agent is the name of an Observer Agent of the organization (GET /agents; create one with POST /agents). An unknown name, or one two agents share, fails validation. A metric whose source runs on an agent but names none is accepted with a warning: it gets no data until an agent is assigned. Each metric entry in diff shows the agent it resolved to.

Pages keep the per-metric settings edited in the console (public label, uptime bar); the document controls which metrics a page shows, their group and order. A page entry in diff lists metrics added, removed and changed.

A heartbeat metric (source_type: heartbeat) must not name an agent; the document fails validation if it does. Its thresholds are ignored, because they derive from period_seconds and grace_seconds. The ping URL is never part of the document (GET /metrics//heartbeat returns it to keys with write:config).

POST

config

apply

Apply a config-as-code document (idempotent upsert by config_key)

curl --request POST \
  --url https://use.observer/api/v1/config/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/yaml' \
  --data '<string>'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/yaml'},
  body: '<string>'
};

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

import requests

url = "https://use.observer/api/v1/config/apply"

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

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

print(response.text)

{
  "dry_run": true,
  "pruned": true,
  "summary": {
    "created": 123,
    "updated": 123,
    "unchanged": 123,
    "pruned": 123
  },
  "diff": {
    "metrics": [
      {
        "key": "<string>",
        "action": "create",
        "agent": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>"
        }
      }
    ],
    "services": [
      {
        "key": "<string>",
        "action": "create"
      }
    ],
    "slos": [
      {
        "key": "<string>",
        "action": "create"
      }
    ],
    "pages": [
      {
        "key": "<string>",
        "action": "create",
        "metrics": {
          "added": [
            "<string>"
          ],
          "removed": [
            "<string>"
          ],
          "changed": [
            "<string>"
          ]
        }
      }
    ]
  },
  "warnings": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "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"
}

{
  "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.

Query Parameters

dryRun

boolean

default:false

Plan only: return the diff and change nothing. dry_run is accepted too.

prune

boolean

default:false

Also delete config-managed objects that the document no longer names.

Body

The ConfigDocument as YAML.

Response

Applied, or planned when dryRun is set. warnings is always present (empty when there is nothing to report); each entry is { path, message }: ignored top-level keys, and agent-run metrics that name no agent.

dry_run

boolean

pruned

boolean

summary

object

Show child attributes

diff

object

Per bucket, one entry per object the document names (and, with prune, each pruned object).

Show child attributes

warnings

object[]

Show child attributes

Apply a config-as-code document (idempotent upsert by config_key)

curl --request POST \
  --url https://use.observer/api/v1/config/apply \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/yaml' \
  --data '<string>'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/yaml'},
  body: '<string>'
};

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

import requests

url = "https://use.observer/api/v1/config/apply"

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

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

print(response.text)

{
  "dry_run": true,
  "pruned": true,
  "summary": {
    "created": 123,
    "updated": 123,
    "unchanged": 123,
    "pruned": 123
  },
  "diff": {
    "metrics": [
      {
        "key": "<string>",
        "action": "create",
        "agent": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>"
        }
      }
    ],
    "services": [
      {
        "key": "<string>",
        "action": "create"
      }
    ],
    "slos": [
      {
        "key": "<string>",
        "action": "create"
      }
    ],
    "pages": [
      {
        "key": "<string>",
        "action": "create",
        "metrics": {
          "added": [
            "<string>"
          ],
          "removed": [
            "<string>"
          ],
          "changed": [
            "<string>"
          ]
        }
      }
    ]
  },
  "warnings": [
    {
      "path": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "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"
}

{
  "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

Audit log

Apply config

Authorizations

Query Parameters

Body

Response