[RFC 8615 OpenAPI, RFC 9727 catalog, RFC 8594 Sunset]

Discovery and governance

Argus publishes its public API surface through standards-aligned discovery: an RFC 8615 well-known OpenAPI 3.1 descriptor (JSON and YAML), an RFC 9727 link-set that points at every machine-readable artefact, a tenant-aware reflective listing of the data schemas the caller can reach right now, and RFC 8594 Sunset and Deprecation headers so partners can plan migrations the same way they would for any open-standards API.

Well-known OpenAPI descriptors

`GET /.well-known/openapi.json` and `GET /.well-known/openapi.yaml` serve the curated public OpenAPI 3.1 contract at the RFC 8615 well-known path. Both are unauthenticated, return strong ETags derived from a content hash, and honour `If-None-Match` with `304 Not Modified` so tooling can cache aggressively. The descriptor is filtered against the public denylist sourced from `app/core/public_contract_filter.py`, which mirrors the `denylist` array on the website contract: internal, admin, and platform-only routes never appear in the response. Both formats are byte-for-byte equivalent in semantic content; only the serialisation differs.

API catalog link-set

`GET /.well-known/api-catalog` returns an RFC 9727 link-set so partners can discover every machine-readable artefact from a single anchor. Each entry advertises `service-desc` (the OpenAPI JSON and YAML well-known URIs), `service-doc` (the published documentation site), and `service-meta` (the ML-DSA-65 provenance verify-key well-known, with `rel="provenance-verify-keys"`). Content-Type is `application/linkset+json`. Use this as the bootstrapping endpoint for tooling: a single fetch yields enough URIs to drive the rest of the integration.

Reflective data-schema listing

`GET /v1/discovery/data-schemas` is a tenant-aware reflective listing of the JSON schemas the caller can reach right now. It requires the `argus:discovery:read` scope on a bearer token. Results are filtered by `tenant_id` and `organization_id` from the auth context and clamped against the caller’s `secrecy_level` clearance. Optional `include_federated=true` extends the listing to upstream sources reachable via approved Communities of Interest (COI) channels; optional `secrecy_max=` clamps results to a clearance level. Each schema entry advertises a canonical `schema_url` under `/.well-known/schemas/{id}.json` for offline contract pinning. Every call writes a `discovery.schemas.read` audit event.

Sunset and Deprecation headers

Argus emits RFC 8594 `Sunset` and `Deprecation` headers automatically on every route listed in `deprecation-matrix.json`. Both values are IMF-fixdate timestamps (`Sun, 06 Nov 2026 08:49:37 GMT`). A companion `Link: <successor-version-url>; rel="successor-version"` points at the replacement so client tooling can surface the migration path without reading the changelog. There is no opt-in: the middleware applies uniformly across the surface, so partners can wire a single header check into their HTTP client and surface deprecation notices to operators long before the sunset date.

How partners track contract versions

The published contract version sits in the OpenAPI `info.version` field at `/.well-known/openapi.json` (currently `2026.4.0`). The deprecation matrix is partitioned by contract version, so a single `GET` against the well-known plus a header check on the live request gives you both the published surface and any per-route migration windows.

Tooling: Postman, Insomnia, OpenAPI generators

Because the descriptor lives at the RFC 8615 well-known path, every standards-aware client can find it without bespoke configuration. Postman: import directly from `https://api.knogin.com/.well-known/openapi.json`. Insomnia: same URL, `Import From URL`. Stoplight Studio, Redocly CLI, and `openapi-generator-cli` resolve the URL the same way. Code generators that prefer YAML can pull the equivalent payload from `/.well-known/openapi.yaml`. Programmatic partners typically start from `/.well-known/api-catalog`, follow the `service-desc` link, then cache against the ETag the OpenAPI well-known returns.

Discovery round-trip

# 1. Bootstrap from the API catalog link-set
curl https://api.knogin.com/.well-known/api-catalog

# 2. Fetch the OpenAPI 3.1 descriptor (JSON or YAML)
curl https://api.knogin.com/.well-known/openapi.json
curl https://api.knogin.com/.well-known/openapi.yaml

# 3. List the data schemas the caller's tenant + clearance can see
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.knogin.com/v1/discovery/data-schemas?include_federated=true"

# 4. Watch for Sunset / Deprecation headers on any live route
curl -i -H "Authorization: Bearer $TOKEN" https://api.knogin.com/v1/profiles/abc | head
# Sunset: Sun, 06 Nov 2026 08:49:37 GMT
# Deprecation: Sun, 06 Nov 2026 08:49:37 GMT
# Link: <https://api.knogin.com/v2/profiles/abc>; rel="successor-version"

Reflective data-schemas response

{
  "tenant_id": "tnt_123",
  "schemas": [
    {
      "id": "argus.profile.v1",
      "title": "Profile",
      "secrecy_level": "standard",
      "operations": [
        "GET /v1/profiles/{id}",
        "POST /v1/profiles/{id}/enrich"
      ],
      "schema_url": "https://api.knogin.com/.well-known/schemas/argus.profile.v1.json"
    }
  ],
  "federated_sources": []
}

Ready to wire discovery into your tooling?

Open the API reference for the curated public contract, or talk to Knogin if you need help bootstrapping a partner integration from the well-known endpoints.