> ## Documentation Index > Fetch the complete documentation index at: https://docs.use.observer/llms.txt > Use this file to discover all available pages before exploring further. # 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/{id}/heartbeat returns it to keys with write:config). ## OpenAPI ````yaml api-reference/openapi.json POST /config/apply openapi: 3.1.0 info: title: Observer API version: 1.0.0 description: >- Public API for Observer: read services, metrics, SLOs and SLA statements; manage incidents, maintenance windows, manual metric status, config as code and Observer Agents. Bearer-auth via API keys (obs_pub_…), scoped per key. RFC 7807 problem-detail errors. Cursor pagination. Rate limits are per organization. servers: - url: https://use.observer/api/v1 security: - bearerAuth: [] paths: /config/apply: post: tags: - config summary: Apply a config-as-code document (idempotent upsert by config_key) description: >- 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/{id}/heartbeat returns it to keys with write:config). operationId: applyConfig parameters: - name: dryRun in: query description: >- Plan only: return the diff and change nothing. `dry_run` is accepted too. schema: type: boolean default: false - name: prune in: query description: >- Also delete config-managed objects that the document no longer names. schema: type: boolean default: false requestBody: required: true content: application/yaml: schema: type: string description: The ConfigDocument as YAML. application/json: schema: $ref: '#/components/schemas/ConfigDocument' responses: '200': description: >- 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. content: application/json: schema: type: object properties: dry_run: type: boolean pruned: type: boolean summary: type: object properties: created: type: integer updated: type: integer unchanged: type: integer pruned: type: integer diff: $ref: '#/components/schemas/ConfigDiff' warnings: type: array items: type: object properties: path: type: string message: type: string '400': description: >- `invalid_body`: a JSON content type was sent and the body is not valid JSON. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: >- `unauthenticated`: no bearer token was sent, or the key is invalid or revoked. `detail` distinguishes the two. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: >- `forbidden`: the key lacks `write:config`. `plan_does_not_permit_api`: the plan does not include the public API. `item_suspended_plan`: the document changes objects that are suspended because the organization is over its plan limits (`errors` names each one). Nothing is applied. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: '`not_found`: not found. Cross-tenant ids return the same response.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '413': description: '`payload_too_large`: the document exceeds the 1 MB limit.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': description: >- `config_invalid`: the document parsed but its contents failed validation. Nothing is applied. The body carries `errors` (a list of `{ path, message }`) and the same `warnings` list as a successful response. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: >- `rate_limited`: the organization's per-minute or daily request limit is used up (`limit.window` says which). Limits are per organization, shared by every key. The response carries `Retry-After` and `retry_after`, in seconds. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: '`internal_error`: an unhandled server error. Safe to retry.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: - write:config components: schemas: ConfigDocument: type: object description: >- A config-as-code document. GET /config/export returns one for the current state. properties: apiVersion: type: string const: observer/v1 metrics: type: array items: type: object required: - key - title - source_type - source_config properties: key: type: string pattern: ^[a-z0-9][a-z0-9-]{0,62}$ description: >- Stable id in the document: lowercase letters, digits, dashes. Apply matches existing metrics by it. title: type: string description: type: string source_type: type: string enum: - prometheus - http - tcp - dns - icmp - tls_cert - grpc - websocket - mtls_http - database - otlp - cloudwatch - custom - loki - elasticsearch - host - manual - heartbeat - alert description: >- What produces the samples. heartbeat and manual need no agent; every other type runs on an Observer Agent. source_config: type: object description: >- Shape depends on source_type (see the matching SourceConfig schema). Secrets are env-var names (…_ref), resolved on the agent host. thresholds: type: object description: >- Per-sample status: healthy match wins, else unhealthy match, else degraded. Ignored for heartbeats. properties: healthy_operation: type: string enum: - over - under - equal description: 'Strict comparison: over is >, under is <, equal is =.' healthy_value: type: - number - string unhealthy_operation: type: string enum: - over - under - equal description: 'Strict comparison: over is >, under is <, equal is =.' unhealthy_value: type: - number - string agent: type: string description: >- Name of the Observer Agent that runs it (GET /agents). Must exist and be unique. Not allowed on heartbeat metrics. interval: type: integer description: Poll interval in seconds. interval_agent_push: type: integer description: Push interval in seconds (plan floor applies). dwell_seconds_to_breach: type: integer description: Seconds a worse status must hold before the metric flips. dwell_seconds_to_recover: type: integer description: Seconds a better status must hold before the metric flips. allOf: - if: properties: source_type: const: prometheus required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigPrometheus' - if: properties: source_type: const: http required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigHttp' - if: properties: source_type: const: tcp required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigTcp' - if: properties: source_type: const: dns required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigDns' - if: properties: source_type: const: icmp required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigIcmp' - if: properties: source_type: const: tls_cert required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigTlsCert' - if: properties: source_type: const: grpc required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigGrpc' - if: properties: source_type: const: websocket required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigWebsocket' - if: properties: source_type: const: mtls_http required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigMtlsHttp' - if: properties: source_type: const: database required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigDatabase' - if: properties: source_type: const: otlp required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigOtlp' - if: properties: source_type: const: cloudwatch required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigCloudwatch' - if: properties: source_type: const: custom required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigCustom' - if: properties: source_type: const: loki required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigLoki' - if: properties: source_type: const: elasticsearch required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigElasticsearch' - if: properties: source_type: const: host required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigHost' - if: properties: source_type: const: manual required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigManual' - if: properties: source_type: const: heartbeat required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigHeartbeat' - if: properties: source_type: const: alert required: - source_type then: properties: source_config: $ref: '#/components/schemas/SourceConfigAlert' services: type: array items: type: object required: - key - name properties: key: type: string pattern: ^[a-z0-9][a-z0-9-]{0,62}$ name: type: string description: type: string slos: type: array items: type: object required: - key - metric - target_pct - window_days properties: key: type: string pattern: ^[a-z0-9][a-z0-9-]{0,62}$ metric: type: string description: Key of a metric in this document. name: type: string target_pct: type: number exclusiveMinimum: 0 exclusiveMaximum: 100 window_days: type: integer minimum: 1 maximum: 365 public: type: boolean unknown_policy: type: string enum: - down - exclude - up default: down maintenance_policy: type: string enum: - exclude - count default: exclude pages: type: array items: type: object required: - key - subdomain properties: key: type: string pattern: ^[a-z0-9][a-z0-9-]{0,62}$ subdomain: type: string pattern: ^[a-z0-9-]{3,32}$ description: Globally unique; .use.observer. title: type: string metrics: type: array description: Metric keys in display order, or { metric, group?, order? }. items: anyOf: - type: string - type: object required: - metric properties: metric: type: string group: type: string order: type: integer ConfigDiff: type: object description: >- Per bucket, one entry per object the document names (and, with prune, each pruned object). properties: metrics: type: array items: type: object required: - key - action properties: key: type: string action: type: string enum: - create - update - unchanged - prune agent: type: - object - 'null' description: The agent the metric resolves to. properties: id: type: string format: uuid name: type: string services: type: array items: type: object required: - key - action properties: key: type: string action: type: string enum: - create - update - unchanged - prune slos: type: array items: type: object required: - key - action properties: key: type: string action: type: string enum: - create - update - unchanged - prune pages: type: array items: type: object required: - key - action properties: key: type: string action: type: string enum: - create - update - unchanged - prune metrics: type: object description: >- Present when the page's metric list changes: metric keys added, removed, and regrouped or reordered. properties: added: type: array items: type: string removed: type: array items: type: string changed: type: array items: type: string Problem: type: object required: - type - title - status example: type: https://docs.use.observer/api/getting-started/errors#forbidden title: forbidden status: 403 detail: 'missing scope: write:incidents' properties: type: type: string format: uri description: Errors reference URI with the title token as the fragment. example: https://docs.use.observer/api/getting-started/errors#forbidden title: type: string description: Stable error token. Branch on this, not on detail. status: type: integer detail: type: string description: Human-readable explanation. Wording may change. retry_after: type: integer description: >- 429 only: seconds until the exhausted window resets (mirrors Retry-After). limit: type: object description: '429 only: which organization limit was hit.' properties: scope: type: string enum: - organization window: type: string enum: - minute - day max: type: integer plan: type: string errors: type: array description: >- Validation failures (config_invalid, invalid_customer_targeting): one entry per problem. items: type: object properties: path: type: string message: type: string warnings: type: array description: >- config_invalid only: the same non-fatal warnings a successful apply returns. items: type: object properties: path: type: string message: type: string unknown_customers: type: array description: >- unknown_customers only: the submitted values that matched no customer in your organization. items: type: string referenced_by: type: object description: >- in_use only: what depends on the object (slos, pages: lists of { id, config_key, name }; subscribers: a count). quota: type: object description: >- quota_exceeded / feature_locked on a create, item_suspended_plan on a write to a suspended item: the plan limit involved. properties: capability: type: string used: type: - integer - 'null' cap: type: - integer - 'null' plan: type: - string - 'null' upgrade: type: object description: >- Plan-limit problems only, when a higher plan lifts the limit: the smallest such plan and the pricing page. properties: plan: type: string label: type: string url: type: string format: uri securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: obs_pub_ description: >- An organization API key (obs_pub_…) sent as `Authorization: Bearer `. Each key carries scopes; an endpoint lists the scope it needs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.