# info.description
A credential-free, read-only API for agents consuming INTERNETMON's independent regional probe observations. An observed failure is evidence from a configured probe, not a definitive vendor outage declaration or root-cause determination. HTTP 4xx client responses and unavailable monitoring coverage remain distinct from availability failures. Public v1 deliberately excludes verbose request/response diagnostics, credentials, cookies, request bodies, query values, and arbitrary provider error text. Every timestamp is RFC 3339 UTC; historical intervals are inclusive at start and exclusive at end. Successful JSON projections are capped at 2 MiB; an oversized projection fails closed with `response_too_large` and callers should narrow their filters.

# tags[].description
Public API discovery and schema documents.

# tags[].description
Public company and monitored-endpoint identity.

# tags[].description
Bounded historical episodes derived from observed failure checks.

# tags[].description
Company-level availability evidence over an exact UTC interval.

# paths./api.get.description
Returns links to the v1 collections and this OpenAPI document. This route and every v1 route are unauthenticated and read-only.

# paths./api.head.responses.200.description
The same headers as GET, without a response body.

# paths./api.options.summary
Inspect the public read-only method contract

# paths./api/v1/companies.get.description
Returns canonical company identifiers and currently enabled public endpoint identities. The optional search is limited to company identity metadata; it never searches errors or diagnostics. Unknown and duplicate query parameters are rejected.

# paths./api/v1/failures.get.description
Returns current non-success observations grouped by endpoint, with availability failures, HTTP 4xx client responses, healthy regions, and unavailable monitoring coverage kept separate. A latest 4xx can coexist with an earlier unresolved availability episode; inspect `availability_open` independently from `current.state`. A partial response is still HTTP 200 and reports missing coverage explicitly. This collection contains no verbose diagnostic record.

# paths./api/v1/failures.get.responses.200.description
Current observed failure state. Inspect `partial` and `coverage` before drawing conclusions.

# paths./api/v1/incidents.get.description
Returns bounded historical episodes assembled from regional failure checks. `start` is inclusive and `end` is exclusive. First/last-observed timestamps are measurement boundaries, not exact outage boundaries. `ended_at` is a typed closure boundary and only `end_reason: recovered` establishes observed recovery. Cursors are opaque and bound to the normalized filter set. No full-text diagnostic search or verbose detail is exposed.

# paths./api/v1/incidents.get.responses.200.description
A page of observed incidents for the exact interval.

# paths./api/v1/companies/{company_id}/availability.get.summary
Assess one company's observed availability

# paths./api/v1/companies/{company_id}/availability.get.description
Combines endpoint and regional observations for one canonical company over `[start, end)`. Complete-company outage and degradation fields describe what INTERNETMON observed; they are not vendor incident confirmations. `complete_company_outage_observed` can be true only without region or severity filters, when every enabled company endpoint in every configured region has complete overlapping evidence. Filtered requests remain scoped evidence.

# paths./api/v1/companies/{company_id}/availability.get.responses.200.description
Observed company availability for the exact interval.

# components.headers.CacheControl.description
Public freshness and revalidation guidance. Consumers should honor it rather than polling continuously.

# components.headers.ETag.description
Validator for conditional GET using `If-None-Match`.

# components.parameters.CompanySearch.description
Bounded case-insensitive company-name search. Error and diagnostic text is never searched.

# components.parameters.CompanyIdPath.description
Opaque canonical company identifier returned by `/api/v1/companies`. Do not derive it from the display name.

# components.parameters.CompanyIdQuery.description
Exact canonical company identifier returned by `/api/v1/companies`.

# components.parameters.EndpointId.description
Exact positive endpoint identifier from the public company collection.

# components.parameters.Impact.description
Select availability-impacting failures, excluded HTTP 4xx client responses, or both.

# components.parameters.IncidentCategory.description
The historical collection currently exposes availability failures only. HTTP 4xx client-response episodes remain excluded.

# components.parameters.Start.description
Inclusive interval start. Must be an offset-aware RFC 3339 timestamp; natural-language and offset-free timestamps are rejected.

# components.parameters.End.description
Exclusive interval end. Must be an offset-aware RFC 3339 timestamp later than `start` and within the documented retention/window bound.

# components.parameters.Limit.description
Maximum records to return. Values outside the allowed range are rejected, not silently expanded.

# components.parameters.Cursor.description
Opaque pagination cursor returned by the same route and exact filter set. Do not inspect or modify it.

# components.responses.NotModified.description
The current representation matches `If-None-Match`; no body is returned.

# components.responses.BadRequest.description
Invalid, unsupported, or duplicated parameter.

# components.responses.NotFound.description
The requested current public resource does not exist.

# components.responses.Unavailable.description
No usable fresh monitoring snapshot is available, aggregation failed, or the requested projection exceeded the 2 MiB public response ceiling. Inspect the bounded problem code (including `temporarily_unavailable` or `response_too_large`), honor `Retry-After`, and narrow the query when applicable. A 503 is not evidence that a monitored company failed.

# components.schemas.SchemaVersion.description
Version of the public response contract.

# components.schemas.UtcTimestamp.description
Offset-aware RFC 3339 timestamp normalized to UTC.

# components.schemas.CompanyId.description
Opaque canonical public company identifier.

# components.schemas.EpisodeEndReason.description
Why observation of a regional failure episode ended. Only `recovered` is evidence of a passing recovery check.

# components.schemas.AvailabilityClassification.description
Bounded machine classification of the observed company-level evidence.

# components.schemas.Company.properties.endpoint_count.description
Number of endpoints currently active for this company. A retained historical-only company can have zero.

# components.schemas.Company.properties.historical_endpoint_count.description
Distinct endpoint IDs with an enabled public revision in the retained 90-day discovery window.

# components.schemas.EndpointReference.properties.url.description
Credential-free scheme and host identity plus `/` or a redacted `/…` path marker. Query values, fragments, user information, and the original path are never public.

# components.schemas.EndpointReference.properties.revision_id.description
Opaque public metadata revision identity. Present on historical endpoint projections so edits of one numeric endpoint ID remain unambiguous.

# components.schemas.EndpointReference.properties.metadata_attribution.description
Present only for pre-ledger observations. Public metadata is the credential-free snapshot that existed at migration, not proof that the same label was configured at the observation time; coverage remains partial and conclusions are confidence-capped.

# components.schemas.Coverage.properties.incomplete_path_count.description
Present on the current-failures collection.

# components.schemas.CurrentObservation.properties.revision_id.description
Opaque public metadata revision attached to this current observation when available.

# components.schemas.Observation.properties.availability_open.description
True when a regional availability-failure episode remains open at the current query boundary. This can be true even when the latest individual check is a 4xx client response.

# components.schemas.CurrentFailure.properties.availability_impact.description
False for HTTP 4xx-only client responses.

# components.schemas.RegionalEpisode.properties.revision_id.description
Opaque public metadata revision that owned this episode.

# components.schemas.RegionalEpisode.properties.ended_at.description
Observed episode closure time. Omitted while the episode is still open; this field does not by itself imply recovery.

# components.schemas.RegionalEpisode.properties.recovered_at.description
Present only when `end_reason` is `recovered`; configuration or monitoring lifecycle boundaries are never presented as recovery.

# components.schemas.RegionalEpisode.properties.open_at_window_end.description
Whether this episode was still active at the requested exclusive end instant, independently of whether it ended later.

# components.schemas.RegionalEpisode.properties.episode_failure_check_count.description
Count for the complete compact episode; it can include checks outside the requested interval.

# components.schemas.Incident.properties.id.description
Opaque deterministic identifier for the currently observed clustered evidence. Consumers must not treat it as a permanent vendor incident ID.

# components.schemas.Incident.properties.ended_at.description
Latest observed regional closure when every contributing regional episode has ended; null while any remains open.

# components.schemas.Incident.properties.recovered_at.description
Non-null only when every contributing regional episode ended through an observed recovery and the incident was not active at the requested window end.

# components.schemas.Incident.properties.open_at_window_end.description
Whether any contributing regional episode was active at the requested exclusive end instant, even if it ended later.

# components.schemas.Incident.properties.episode_failure_check_count.description
Sum of complete compact regional-episode counts; it can include checks outside the requested interval.

# components.schemas.AvailabilityAssessment.properties.complete_company_outage_observed.description
True only for an unfiltered full-company/full-region assessment with complete overlapping failure evidence; always false for region- or severity-scoped requests.

# components.schemas.AvailabilityAssessment.properties.summary.description
Bounded server-authored explanation of the structured assessment, never arbitrary provider error text.

# components.schemas.AvailabilityTotals.description
Exact eligible check counts. HTTP 4xx client responses are reported separately and excluded from the availability denominator.

# components.schemas.EndpointAvailability.properties.incident_ids.description
IDs of this endpoint's incidents retained in the bounded top-level `incidents` list.

# components.schemas.CompanyAvailabilityCoverage.properties.configured_endpoint_revisions.description
Public endpoint metadata revisions overlapping the requested historical window.

# components.schemas.IncidentsResponse.properties.incidents_truncated.description
True when a regional compact-episode budget omitted incident evidence. In that case `page.total` is only the number of incidents retained in this projection, not the historical total.

# components.schemas.CompanyAvailabilityResponse.properties.incident_count.description
Total availability incidents before the bounded top-level list is truncated.

# components.schemas.Problem.properties.error.properties.details.description
Bounded structured validation details. It never contains endpoint configuration or provider diagnostics.