{"id":"discovery-and-governance","title":"Discovery and governance","description":"Standards-aligned API discovery (RFC 8615 OpenAPI well-known, RFC 9727 API catalog, reflective tenant-aware data schema listing) plus Sunset and Deprecation header behaviour driven by the published deprecation matrix.","lastUpdated":"2026-05-08","sections":[{"id":"discovery-openapi-wellknown","title":"GET /.well-known/openapi.json · Fetch the OpenAPI well-known descriptor (JSON)","content":"Route: GET /.well-known/openapi.json\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the curated public OpenAPI 3.1 contract at the RFC 8615 well-known path. No authentication required.\n\nIntegration notes:\n- RFC 8615 well-known URI: tooling can locate the OpenAPI descriptor without bespoke configuration.\n- Content-Type `application/json`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.\n- The descriptor is filtered against the public denylist sourced from `app/core/public_contract_filter.py`, which mirrors the `denylist` array in this contract. Internal, admin, and platform-only routes are never present in the response.\n- Response is identical to `openapi.yaml` in semantic content; only the serialisation differs.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/.well-known/openapi.json","description":"Request example"},{"language":"json","code":"{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"Argus External API\",\n    \"version\": \"2026.4.0\"\n  },\n  \"paths\": { \"/v1/jobs\": { \"...\": \"...\" } }\n}","description":"Response example"}]},{"id":"discovery-openapi-wellknown-yaml","title":"GET /.well-known/openapi.yaml · Fetch the OpenAPI well-known descriptor (YAML)","content":"Route: GET /.well-known/openapi.yaml\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the same curated public OpenAPI 3.1 contract as YAML at the RFC 8615 well-known path. No authentication required.\n\nIntegration notes:\n- RFC 8615 well-known URI: tooling that prefers YAML can locate the OpenAPI descriptor without bespoke configuration.\n- Content-Type `application/yaml`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.\n- Semantic content is identical to `openapi.json`; the same denylist filtering applies.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/.well-known/openapi.yaml","description":"Request example"},{"language":"text","code":"openapi: 3.1.0\ninfo:\n  title: Argus External API\n  version: 2026.4.0\npaths:\n  /v1/jobs:\n    get: { ... }\n","description":"Response example"}]},{"id":"discovery-api-catalog","title":"GET /.well-known/api-catalog · Fetch the API catalog link-set","content":"Route: GET /.well-known/api-catalog\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the RFC 9727 link-set pointing at the OpenAPI descriptors, the published documentation site, and the provenance verify-key well-known. No authentication required.\n\nIntegration notes:\n- RFC 9727 link-set format: a single `linkset` array of `{ anchor, service-desc, service-doc, service-meta }` objects.\n- The `service-desc` entries advertise both the JSON and YAML OpenAPI well-known URIs.\n- The `service-meta` entry advertises the ML-DSA-65 provenance verify-key well-known so partners can locate post-quantum verification material from a single root.\n- Content-Type `application/linkset+json`.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/.well-known/api-catalog","description":"Request example"},{"language":"json","code":"{\n  \"linkset\": [\n    {\n      \"anchor\": \"https://api.knogin.com/\",\n      \"service-desc\": [\n        { \"href\": \"https://api.knogin.com/.well-known/openapi.json\", \"type\": \"application/json\" },\n        { \"href\": \"https://api.knogin.com/.well-known/openapi.yaml\", \"type\": \"application/yaml\" }\n      ],\n      \"service-doc\": [\n        { \"href\": \"https://knogin.com/en/docs/api-reference\", \"type\": \"text/html\" }\n      ],\n      \"service-meta\": [\n        { \"href\": \"https://api.knogin.com/.well-known/provenance-keys/ml-dsa-65\", \"type\": \"application/json\", \"rel\": \"provenance-verify-keys\" }\n      ]\n    }\n  ]\n}","description":"Response example"}]},{"id":"discovery-data-schemas","title":"GET /v1/discovery/data-schemas · List visible data schemas for the caller","content":"Route: GET /v1/discovery/data-schemas\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReflective endpoint listing the JSON schemas the caller's tenant and clearance can reach right now, with optional COI federation.\n\nIntegration notes:\n- Requires the `argus:discovery:read` scope on a bearer token.\n- Tenant scoped: results are filtered by `tenant_id` and `organization_id` from the auth context. Schema visibility is additionally clamped against the caller's `secrecy_level` clearance.\n- Optional query parameter `include_federated=true` extends the listing with upstream sources reachable via approved Communities of Interest (COI) channels.\n- Optional query parameter `secrecy_max=` clamps results to a clearance level; the default is the caller's own clearance.\n- Each schema entry advertises its canonical `schema_url` under `/.well-known/schemas/{id}.json` for offline contract pinning.\n- Audit event `discovery.schemas.read` is emitted on every call.","codeExamples":[{"language":"bash","code":"curl \"https://api.knogin.com/v1/discovery/data-schemas?include_federated=true\" \\\n  -H \"Authorization: Bearer $TOKEN\"","description":"Request example"},{"language":"json","code":"{\n  \"tenant_id\": \"tnt_123\",\n  \"schemas\": [\n    {\n      \"id\": \"argus.profile.v1\",\n      \"title\": \"Profile\",\n      \"secrecy_level\": \"standard\",\n      \"operations\": [\"GET /v1/profiles/{id}\", \"POST /v1/profiles/{id}/enrich\"],\n      \"schema_url\": \"https://api.knogin.com/.well-known/schemas/argus.profile.v1.json\"\n    }\n  ],\n  \"federated_sources\": []\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","oauth-service-tokens","jwks-token-verification","event-delivery-webhooks","graphql-transport-contract","observability-and-tracing","async-jobs","sandbox-environment","provenance-and-compliance"],"markdown":"# Discovery and governance\n\nStandards-aligned API discovery (RFC 8615 OpenAPI well-known, RFC 9727 API catalog, reflective tenant-aware data schema listing) plus Sunset and Deprecation header behaviour driven by the published deprecation matrix.\n\n## GET /.well-known/openapi.json · Fetch the OpenAPI well-known descriptor (JSON)\n\nRoute: GET /.well-known/openapi.json\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the curated public OpenAPI 3.1 contract at the RFC 8615 well-known path. No authentication required.\n\nIntegration notes:\n- RFC 8615 well-known URI: tooling can locate the OpenAPI descriptor without bespoke configuration.\n- Content-Type `application/json`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.\n- The descriptor is filtered against the public denylist sourced from `app/core/public_contract_filter.py`, which mirrors the `denylist` array in this contract. Internal, admin, and platform-only routes are never present in the response.\n- Response is identical to `openapi.yaml` in semantic content; only the serialisation differs.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/.well-known/openapi.json\n```\n\nResponse example\n\n```json\n{\n  \"openapi\": \"3.1.0\",\n  \"info\": {\n    \"title\": \"Argus External API\",\n    \"version\": \"2026.4.0\"\n  },\n  \"paths\": { \"/v1/jobs\": { \"...\": \"...\" } }\n}\n```\n\n## GET /.well-known/openapi.yaml · Fetch the OpenAPI well-known descriptor (YAML)\n\nRoute: GET /.well-known/openapi.yaml\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the same curated public OpenAPI 3.1 contract as YAML at the RFC 8615 well-known path. No authentication required.\n\nIntegration notes:\n- RFC 8615 well-known URI: tooling that prefers YAML can locate the OpenAPI descriptor without bespoke configuration.\n- Content-Type `application/yaml`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.\n- Semantic content is identical to `openapi.json`; the same denylist filtering applies.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/.well-known/openapi.yaml\n```\n\nResponse example\n\n```text\nopenapi: 3.1.0\ninfo:\n  title: Argus External API\n  version: 2026.4.0\npaths:\n  /v1/jobs:\n    get: { ... }\n\n```\n\n## GET /.well-known/api-catalog · Fetch the API catalog link-set\n\nRoute: GET /.well-known/api-catalog\nHost: https://api.knogin.com\nAuth: Public endpoint\nAudience: External integrators\nStability: Stable\n\nReturns the RFC 9727 link-set pointing at the OpenAPI descriptors, the published documentation site, and the provenance verify-key well-known. No authentication required.\n\nIntegration notes:\n- RFC 9727 link-set format: a single `linkset` array of `{ anchor, service-desc, service-doc, service-meta }` objects.\n- The `service-desc` entries advertise both the JSON and YAML OpenAPI well-known URIs.\n- The `service-meta` entry advertises the ML-DSA-65 provenance verify-key well-known so partners can locate post-quantum verification material from a single root.\n- Content-Type `application/linkset+json`.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/.well-known/api-catalog\n```\n\nResponse example\n\n```json\n{\n  \"linkset\": [\n    {\n      \"anchor\": \"https://api.knogin.com/\",\n      \"service-desc\": [\n        { \"href\": \"https://api.knogin.com/.well-known/openapi.json\", \"type\": \"application/json\" },\n        { \"href\": \"https://api.knogin.com/.well-known/openapi.yaml\", \"type\": \"application/yaml\" }\n      ],\n      \"service-doc\": [\n        { \"href\": \"https://knogin.com/en/docs/api-reference\", \"type\": \"text/html\" }\n      ],\n      \"service-meta\": [\n        { \"href\": \"https://api.knogin.com/.well-known/provenance-keys/ml-dsa-65\", \"type\": \"application/json\", \"rel\": \"provenance-verify-keys\" }\n      ]\n    }\n  ]\n}\n```\n\n## GET /v1/discovery/data-schemas · List visible data schemas for the caller\n\nRoute: GET /v1/discovery/data-schemas\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReflective endpoint listing the JSON schemas the caller's tenant and clearance can reach right now, with optional COI federation.\n\nIntegration notes:\n- Requires the `argus:discovery:read` scope on a bearer token.\n- Tenant scoped: results are filtered by `tenant_id` and `organization_id` from the auth context. Schema visibility is additionally clamped against the caller's `secrecy_level` clearance.\n- Optional query parameter `include_federated=true` extends the listing with upstream sources reachable via approved Communities of Interest (COI) channels.\n- Optional query parameter `secrecy_max=` clamps results to a clearance level; the default is the caller's own clearance.\n- Each schema entry advertises its canonical `schema_url` under `/.well-known/schemas/{id}.json` for offline contract pinning.\n- Audit event `discovery.schemas.read` is emitted on every call.\n\nRequest example\n\n```bash\ncurl \"https://api.knogin.com/v1/discovery/data-schemas?include_federated=true\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nResponse example\n\n```json\n{\n  \"tenant_id\": \"tnt_123\",\n  \"schemas\": [\n    {\n      \"id\": \"argus.profile.v1\",\n      \"title\": \"Profile\",\n      \"secrecy_level\": \"standard\",\n      \"operations\": [\"GET /v1/profiles/{id}\", \"POST /v1/profiles/{id}/enrich\"],\n      \"schema_url\": \"https://api.knogin.com/.well-known/schemas/argus.profile.v1.json\"\n    }\n  ],\n  \"federated_sources\": []\n}\n```\n\n## Related Topics\n\n- [Identity and app registration](https://knogin.com/api/docs/identity-app-registration)\n- [OAuth and service tokens](https://knogin.com/api/docs/oauth-service-tokens)\n- [JWKS and token verification](https://knogin.com/api/docs/jwks-token-verification)\n- [Event delivery and webhooks](https://knogin.com/api/docs/event-delivery-webhooks)\n- [GraphQL transport contract](https://knogin.com/api/docs/graphql-transport-contract)\n- [Observability and tracing](https://knogin.com/api/docs/observability-and-tracing)\n- [Async jobs](https://knogin.com/api/docs/async-jobs)\n- [Sandbox environment](https://knogin.com/api/docs/sandbox-environment)\n- [Provenance and compliance](https://knogin.com/api/docs/provenance-and-compliance)","metadata":{"readingTime":"8 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}