---
title: "Customer read-only API contract"
description: "A reference contract for a future approval-gated, organization-isolated HARBINGER API covering objects, observations, change, evidence, and unresolved gaps."
updated: "27 August 2026"
availability: "PRIVATE PREVIEW CONTRACT"
candidate_route: "/docs/api/overview"
---

# Customer read-only API contract

A reference contract for a future approval-gated, organization-isolated HARBINGER API covering objects, observations, change, evidence, and unresolved gaps.

**PRIVATE PREVIEW CONTRACT:** Customer OpenAPI contract and fixed reference responses published · no customer operational endpoint or credentials

## A public fixed-example endpoint and a separate customer contract

The stateless synthetic version-pinned Public Demo serves precomputed responses now with equal corporate and financial record review and industrial supply-chain paths. Separately available for review are the approval-only customer OpenAPI contract, a fixed fictional financial reference response, and an regional customer-infrastructure candidate. No shared customer endpoint, customer Sandbox, production address, or self-service credential is available.

Organization, user, purpose, capability, and data-scope enforcement — together with durable audit evidence — are required properties of any future customer environment. The local candidate models named-user identity groups for capability and subject-data grants and pins deployment code to exact storage object versions. A running public demo does not prove that those customer controls have been signed, deployed, or independently verified.

- PUBLIC FIXED EXAMPLES — a stateless GET endpoint serves precomputed synthetic scenarios
- READ_ONLY CUSTOMER CONTRACT — the published customer contract defines GET operations only
- APPROVAL GATED — customer access requires qualification, an agreement, and a prepared environment
- PURPOSE BOUND — every customer request must be bound to an approved purpose and subject domain
- AUTHORITY NONE — no fact, recommendation, approval, command, or execution authority

> **Current status:** The public synthetic demo endpoint serves fixed precomputed examples. The customer API remains a CUSTOMER INFRASTRUCTURE CANDIDATE · NOT DEPLOYED · UNSIGNED; no live collection, customer audit storage, deletion evidence, or production SLA is claimed.

## Five kinds of information in the contract

- Subject and evidence-bound relationship candidates
- Observations bound to source and time
- Change between supported observation states
- Evidence coordinates that return to the approved material
- Unknown, restricted, stale, or otherwise unresolved gaps

## Preview versions make compatibility explicit

The current document contract is `2026-08-27.preview`; the path generation is `/v1`. Preview feedback may change fields and error semantics, so production compatibility is not promised.

Additive optional fields may appear within the same path generation. A change that breaks required fields, resource identity, authority meaning, or interpretation of an existing response must move to a new path generation or an explicitly new contract version and be recorded in the changelog.

- Identify the document contract through OpenAPI `info.version`.
- Separate breaking changes through a new path generation or contract version.
- Set retirement, support, and production migration terms in the applicable customer agreement.
- An executed order and data or security schedule control over public documentation.

## If an environment is approved, authentication and purpose travel together

The request below is a non-operational contract example. Only after an environment is prepared would coordinates and credentials be delivered to an approved administrator through an agreed secure channel. Documentation placeholders confer no access.

**GET · change view**

```bash
curl --fail-with-body \
  -H 'Authorization: Bearer $HARBINGER_PREVIEW_TOKEN' \
  -H 'Harbinger-Data-Purpose: <approved-purpose>' \
  'https://<issued-environment-host>/v1/subjects/<approved-subject-id>/changes'
```

**Inspect the OpenAPI 3.1 contract**

```bash
curl --fail-with-body "${CALAMOPHYTON_DEVELOPER_DOCS_ORIGIN}/openapi.json"
```

---

Published route: /docs/api/overview