Observer Docs

POST

checks

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

{
  "existing": false,
  "experimental": true,
  "check": {
    "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
    "title": "example.com",
    "url": "https://example.com/",
    "interval_minutes": 5,
    "locations": [
      {
        "id": "eu-central",
        "label": "Frankfurt, DE"
      },
      {
        "id": "uk-london",
        "label": "London, GB"
      }
    ]
  },
  "page": {
    "id": "0b7e1d2c-3a4f-4b5e-9c6d-7e8f9a0b1c2d",
    "title": "Acme status",
    "subdomain": "acme",
    "public_url": "https://acme.use.observer/",
    "created": true
  },
  "first_result_eta_seconds": 90,
  "next": "The first result is due in about 90 seconds. Then every 5 minutes. Until the first result the check shows no data. Hosted checks are experimental."
}

{
  "existing": false,
  "experimental": true,
  "check": {
    "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
    "title": "example.com",
    "url": "https://example.com/",
    "interval_minutes": 5,
    "locations": [
      {
        "id": "eu-central",
        "label": "Frankfurt, DE"
      },
      {
        "id": "uk-london",
        "label": "London, GB"
      }
    ]
  },
  "page": {
    "id": "0b7e1d2c-3a4f-4b5e-9c6d-7e8f9a0b1c2d",
    "title": "Acme status",
    "subdomain": "acme",
    "public_url": "https://acme.use.observer/",
    "created": true
  },
  "first_result_eta_seconds": 90,
  "next": "The first result is due in about 90 seconds. Then every 5 minutes. Until the first result the check shows no data. Hosted checks are experimental."
}

{
  "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#quota_exceeded",
  "title": "quota_exceeded",
  "status": 403,
  "detail": "You've reached your plan's hosted check limit (3/3). Upgrade to Starter for more: https://use.observer/pricing",
  "capability": "outside_in_checks",
  "used": 3,
  "cap": 3,
  "plan": "free",
  "quota": {
    "capability": "outside_in_checks",
    "used": 3,
    "cap": 3,
    "plan": "free"
  },
  "upgrade": {
    "plan": "starter",
    "label": "Starter",
    "url": "https://use.observer/pricing"
  }
}

{
  "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#outside_in_unavailable",
  "title": "outside_in_unavailable",
  "status": 503,
  "detail": "Hosted checks are not available yet. Install the agent to monitor this target."
}

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:config

Body

application/json

url

string

required

The website or endpoint to watch. A bare host (example.com) means https. It must be reachable from the public internet: internal addresses, databases and metrics need an Observer Agent.

Maximum string length: 2048

title

string

Name shown on the status page. Defaults to the host.

Maximum string length: 120

page_id

string<uuid>

Status page to add the check to. Defaults to the organization's first page; a new page is created when it has none.

add_to_page

boolean

default:true

false keeps the check off every status page.

Response

already watched

existing

boolean

required

true when the organization already watched this URL; nothing new was created.

check

object

required

Show child attributes

page

object | null

required

The status page showing the check, or null with add_to_page=false.

Show child attributes

string

required

What happens next, in one or two sentences.

experimental

boolean

Always true: hosted checks are an experimental feature.

first_result_eta_seconds

integer

Seconds until the first result is expected (0 when the URL was already watched). Until then the check reads no data.

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

{
  "existing": false,
  "experimental": true,
  "check": {
    "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
    "title": "example.com",
    "url": "https://example.com/",
    "interval_minutes": 5,
    "locations": [
      {
        "id": "eu-central",
        "label": "Frankfurt, DE"
      },
      {
        "id": "uk-london",
        "label": "London, GB"
      }
    ]
  },
  "page": {
    "id": "0b7e1d2c-3a4f-4b5e-9c6d-7e8f9a0b1c2d",
    "title": "Acme status",
    "subdomain": "acme",
    "public_url": "https://acme.use.observer/",
    "created": true
  },
  "first_result_eta_seconds": 90,
  "next": "The first result is due in about 90 seconds. Then every 5 minutes. Until the first result the check shows no data. Hosted checks are experimental."
}

{
  "existing": false,
  "experimental": true,
  "check": {
    "id": "6f1c2a3b-4d5e-4f60-8a7b-9c0d1e2f3a4b",
    "title": "example.com",
    "url": "https://example.com/",
    "interval_minutes": 5,
    "locations": [
      {
        "id": "eu-central",
        "label": "Frankfurt, DE"
      },
      {
        "id": "uk-london",
        "label": "London, GB"
      }
    ]
  },
  "page": {
    "id": "0b7e1d2c-3a4f-4b5e-9c6d-7e8f9a0b1c2d",
    "title": "Acme status",
    "subdomain": "acme",
    "public_url": "https://acme.use.observer/",
    "created": true
  },
  "first_result_eta_seconds": 90,
  "next": "The first result is due in about 90 seconds. Then every 5 minutes. Until the first result the check shows no data. Hosted checks are experimental."
}

{
  "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#quota_exceeded",
  "title": "quota_exceeded",
  "status": 403,
  "detail": "You've reached your plan's hosted check limit (3/3). Upgrade to Starter for more: https://use.observer/pricing",
  "capability": "outside_in_checks",
  "used": 3,
  "cap": 3,
  "plan": "free",
  "quota": {
    "capability": "outside_in_checks",
    "used": 3,
    "cap": 3,
    "plan": "free"
  },
  "upgrade": {
    "plan": "starter",
    "label": "Starter",
    "url": "https://use.observer/pricing"
  }
}

{
  "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#outside_in_unavailable",
  "title": "outside_in_unavailable",
  "status": 503,
  "detail": "Hosted checks are not available yet. Install the agent to monitor this target."
}

Getting started

Account

Status pages

Services

Metrics

SLOs

SLA statements

Incidents

Maintenances

Config as code

Agents

Change events

Audit log

Create a hosted check

Authorizations

Scopes

Body

Response