[Contrat public curé]

API d'Intégration Externe

Cette page documente uniquement le contrat stable d’intégration externe. Elle se limite volontairement aux endpoints et garanties de transport nécessaires aux intégrateurs approuvés.

Docs lisibles par machine Demander un accès avancé

Périmètre de sécurité

This documentation covers the stable external integration contract only. Platform internals, administrative routes, schema-level discovery, and partner-only capabilities are intentionally withheld from the public surface.

Les noms de routes, exemples de tokens et détails de transport restent en anglais canonique pour correspondre exactement au contrat public.

Vérification JWTOAuth et service tokensWebhooksTransport GraphQL uniquementPas de dump de schémaPas de routes internes

URLs de base

Service d'auth: https://auth.knogin.com
Transport GraphQL: https://api.knogin.com/graphql
Docs lisibles par machine: https://knogin.com/api/docs

Contrat public

Identité et enregistrement d'app

Enregistrez une intégration, consultez les scopes approuvés et gérez la gouvernance d’une app externe.

GET

/v1/platform/scopes

List available scopes

Returns the scope catalog that external apps can request during registration and token issuance.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Use this endpoint to build consent or admin approval workflows around approved scopes.
Do not assume unpublished scopes exist or are available to your tenant.

Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/platform/scopes \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "scopes": [
    {
      "name": "webhooks:write",
      "description": "Create and update outbound webhook subscriptions"
    }
  ]
}

GET/POST

/v1/platform/apps

Create and list platform apps

Creates an external integration app record or enumerates the apps already registered for the tenant.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Register a named app before attempting OAuth authorization code or client credentials flows.
The response includes client metadata, approved grants, and tenancy context.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Case sync connector",
    "grant_types": ["client_credentials"],
    "redirect_uris": [],
    "requested_scopes": ["webhooks:write"]
  }'

Réponse

{
  "client_id": "app_123",
  "client_secret": "<write-once-secret>",
  "grant_types": ["client_credentials"],
  "requested_scopes": ["webhooks:write"]
}

GET

/v1/platform/apps/{client_id}

Inspect an integration app

Fetches the current metadata and governance state for a registered app by client identifier.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.

Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/platform/apps/app_123 \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "client_id": "app_123",
  "name": "Case sync connector",
  "grant_types": ["client_credentials"],
  "governance": {
    "allow_service_tokens": true
  }
}

PATCH

/v1/platform/apps/{client_id}/governance

Update app governance

Adjusts governance flags for an existing app without exposing tenant-wide administrative controls.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admins client
Stabilité: Stable

Use governance updates to constrain redirects, service token usage, and other tenant-approved behaviors.
This surface is scoped to the app identified in the path.

Exemple de requête et de réponse

Requête

curl -X PATCH https://auth.knogin.com/v1/platform/apps/app_123/governance \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_service_tokens": true,
    "enforce_pkce": true
  }'

Réponse

{
  "client_id": "app_123",
  "governance": {
    "allow_service_tokens": true,
    "enforce_pkce": true
  }
}

Contrat public

OAuth et service tokens

Utilisez des flux de tokens approuvés pour des intégrations déléguées par utilisateur ou machine-to-machine.

GET

/v1/oauth/authorize

Start OAuth authorization code flow

Initiates the authorization flow for integrations that act on behalf of a signed-in user.

Host: https://auth.knogin.com
Auth: OAuth authorization code
Audience: Intégrateurs externes
Stabilité: Stable

Authorization requests should use the redirect URIs and scopes already approved on the platform app.
PKCE should be used whenever a confidential client secret is not available.

Exemple de requête et de réponse

Requête

https://auth.knogin.com/v1/oauth/authorize?response_type=code&client_id=app_123&redirect_uri=https%3A%2F%2Fintegrator.example%2Fcallback&scope=webhooks%3Awrite&state=<opaque-state>&code_challenge=<pkce-challenge>&code_challenge_method=S256

Réponse

302 redirect to the registered redirect URI with either ?code=<authorization-code> or an OAuth error.

POST

/v1/oauth/token

Exchange or mint access tokens

Issues access tokens via authorization code or client credentials without documenting internal password or session flows.

Host: https://auth.knogin.com
Auth: OAuth auth code or client credentials
Audience: Intégrateurs externes
Stabilité: Stable

Use authorization code for user-delegated access and client credentials for headless service integrations.
Only request scopes that were approved during app registration.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=app_123&client_secret=<client-secret>&scope=webhooks:write"

Réponse

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "webhooks:write"
}

POST

/v1/platform/apps/{client_id}/service-token

Mint a service token

Issues a service token for automation that should not depend on an end-user session.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admins client
Stabilité: Stable

Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.
Keep service-token issuance behind tenant admin approval.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/service-token \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["webhooks:write"]
  }'

Réponse

{
  "token": "<service-token>",
  "expires_at": "2026-03-24T10:00:00Z"
}

POST

/v1/platform/apps/{client_id}/rotate-secret

Rotate an app secret

Rotates a confidential client secret so an external integration can recover or rotate credentials safely.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admins client
Stabilité: Stable

Treat the rotated secret as write-once material and replace it in your secret store immediately.
Rotate secrets before revoking old credentials from automation.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/rotate-secret \
  -H "Authorization: Bearer <admin-access-token>"

Réponse

{
  "client_id": "app_123",
  "client_secret": "<new-write-once-secret>"
}

Contrat public

JWKS et vérification de token

Vérifiez les JWT émis par Knogin avec les clés publiques.

GET

/.well-known/jwks.json

OpenID-compatible JWKS discovery

Publishes public signing keys at the well-known JWKS path for standards-based token validation.

Host: https://auth.knogin.com
Auth: Public
Audience: Intégrateurs externes
Stabilité: Stable

Use the key identifier in the JWT header to select the correct public key.
Cache JWKS responses according to your verifier policy and refresh on unknown key IDs.

Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/.well-known/jwks.json

Réponse

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}

GET

/v1/auth/jwks.json

Versioned JWKS endpoint

Provides the same public signing material under the auth-service versioned API namespace.

Host: https://auth.knogin.com
Auth: Public
Audience: Intégrateurs externes
Stabilité: Stable

Use this variant when your API client standardizes on versioned endpoints.

Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/auth/jwks.json

Réponse

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "2026-03-signing-key",
      "use": "sig"
    }
  ]
}

Contrat public

Diffusion d’événements et webhooks

Créez, testez et observez les livraisons webhook sortantes pour des intégrations approuvées.

GET/POST

/v1/webhooks

Create and list webhooks

Manages outbound webhook subscriptions used to deliver approved event notifications to an external system.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Create subscriptions only for events your integration has been approved to receive.
Outbound webhook secrets should be stored and rotated like any other integration credential.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/webhooks \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://integrator.example/webhooks/argus",
    "events": ["incident.updated"],
    "secret": "<signing-secret>"
  }'

Réponse

{
  "id": "wh_123",
  "url": "https://integrator.example/webhooks/argus",
  "events": ["incident.updated"]
}

GET/PUT/DELETE

/v1/webhooks/{webhook_id}

Inspect, update, or delete a webhook

Manages an individual webhook subscription by identifier.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Use update operations to rotate secrets or adjust event selections without recreating the subscription.

Exemple de requête et de réponse

Requête

curl -X PUT https://auth.knogin.com/v1/webhooks/wh_123 \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["incident.updated", "incident.closed"]
  }'

Réponse

{
  "id": "wh_123",
  "events": ["incident.updated", "incident.closed"]
}

GET

/v1/webhooks/{webhook_id}/deliveries

Review delivery attempts

Returns historical delivery attempts for a webhook so integrators can debug retries and downstream failures.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Use delivery history instead of internal logs to diagnose receiver behavior.
Delivery metadata is limited to the webhook in scope.

Exemple de requête et de réponse

Requête

curl https://auth.knogin.com/v1/webhooks/wh_123/deliveries \
  -H "Authorization: Bearer <access-token>"

Réponse

{
  "deliveries": [
    {
      "id": "dlv_123",
      "status": "succeeded",
      "attempted_at": "2026-03-23T12:00:00Z"
    }
  ]
}

POST

/v1/webhooks/{webhook_id}/test

Send a test webhook

Triggers a synthetic delivery to validate receiver configuration before enabling production traffic.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Use test deliveries when rotating secrets or validating a new endpoint.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/webhooks/wh_123/test \
  -H "Authorization: Bearer <access-token>"

Réponse

{
  "delivery_id": "dlv_test_123",
  "status": "queued"
}

Contrat public

Contrat de transport GraphQL

Connectez-vous au transport GraphQL partagé sans publier le schéma ni l’inventaire des opérations.

POST

/graphql

Use the shared GraphQL transport

Connect to the GraphQL endpoint with bearer tokens and tenant scoping, while operation bundles remain curated and access-controlled.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Public documentation covers transport, headers, tenancy, and error handling only.
Schema dumps, playground access, introspection guidance, and unpublished operations are excluded from the public contract.
Approved partners receive curated operation bundles tied to explicit integration workflows.

Exemple de requête et de réponse

Requête

curl -X POST https://api.knogin.com/graphql \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: <tenant-id>" \
  -d '{
    "query": "<approved GraphQL document>",
    "variables": {}
  }'

Réponse

{
  "data": {
    "result": "Returned for your approved operation bundle"
  }
}

Contrat public

Observability and tracing

W3C Trace Context propagation, OpenTelemetry instrumentation, X-Argus-Trace-ID and X-Argus-Span-ID response headers, and a tenant-scoped trace lookup endpoint.

GET

/v1/observability/traces/{trace_id}

Look up a recorded trace

Returns a tenant-scoped span tree for a W3C trace ID.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:observability:read` scope on a bearer token.
Every Argus response carries `X-Argus-Trace-ID` and `X-Argus-Span-ID`.
Submit `traceparent` on requests to anchor the trace in your own observability backend.
Returns 503 with `query_hint: use_your_backend` if the OTEL backend is briefly unreachable; the trace was still recorded.

Exemple de requête et de réponse

Requête

curl -H "Authorization: Bearer $TOKEN" https://api.knogin.com/v1/observability/traces/0af7651916cd43dd8448eb211c80319c

Réponse

{
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "spans": [...]
}

Contrat public

Async jobs

Enqueue long-running work (intelligence.enrich.bulk, export.bulk, import.bulk, graph.compute), poll status, fetch results, cancel, list, and receive HMAC-signed webhook callbacks. Tenant-scoped with 24h Idempotency-Key replay.

POST

/v1/jobs

Enqueue an async job

Creates an async job for one of the supported kinds and returns an `id` for polling or webhook delivery.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:jobs:write` scope on a bearer token.
Initial supported kinds: `intelligence.enrich.bulk`, `export.bulk`, `import.bulk`, `graph.compute`.
Optional `Idempotency-Key` header (UUID v4 recommended) provides a 24h replay window per tenant. Replays return 200 with the same body and `id` as the original 201.
Optional `callback_url` enables a signed webhook delivery on completion; otherwise poll the status and result endpoints.

Exemple de requête et de réponse

Requête

curl -X POST https://api.knogin.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8b9d8a2e-4a8c-4a7e-8a2e-4a8c4a7e8a2e" \
  -d '{
    "kind": "intelligence.enrich.bulk",
    "payload": { "profile_ids": ["p1", "p2"] },
    "callback_url": "https://partner.example.com/argus-webhook",
    "secrecy_level": "standard"
  }'

Réponse

{
  "id": "01HFXY...",
  "kind": "intelligence.enrich.bulk",
  "status": "queued",
  "created_at": "2026-05-08T12:00:00Z",
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

GET

/v1/jobs/{id}

Get job status

Returns the current state of a single job, including kind, status, progress, timestamps, error, and trace ID.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:jobs:read` scope on a bearer token.
`status` enum: `queued`, `running`, `succeeded`, `failed`, `cancelled`.
Cross-tenant lookups return 404 (never 403) to avoid revealing existence.

Exemple de requête et de réponse

Requête

curl https://api.knogin.com/v1/jobs/01HFXY... \
  -H "Authorization: Bearer $TOKEN"

Réponse

{
  "id": "01HFXY...",
  "kind": "intelligence.enrich.bulk",
  "status": "running",
  "progress_pct": 42,
  "created_at": "2026-05-08T12:00:00Z",
  "updated_at": "2026-05-08T12:00:30Z",
  "completed_at": null,
  "error": null,
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

GET

/v1/jobs/{id}/result

Get job result

Returns the result reference and a short-lived signed URL once the job has succeeded.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:jobs:read` scope on a bearer token.
Returns 202 with `{ status, progress_pct }` while the job is still `queued` or `running`.
Returns 410 once the result has expired (default 30-day retention); the job record itself remains queryable.
The `signed_url` is a short-lived presigned URL into R2; treat it as a credential.

Exemple de requête et de réponse

Requête

curl https://api.knogin.com/v1/jobs/01HFXY.../result \
  -H "Authorization: Bearer $TOKEN"

Réponse

{
  "id": "01HFXY...",
  "result_ref": "r2://argus-jobs/results/01HFXY.json",
  "signed_url": "https://r2-presigned-url..."
}

DELETE

/v1/jobs/{id}

Cancel a job

Requests cancellation of a queued or running job. Idempotent replays of an already-cancelled job return 200.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:jobs:write` scope on a bearer token.
Returns 204 when a `queued` or `running` job is cancelled.
Returns 200 when the job is already `cancelled` (idempotent replay).
Returns 409 only when the job has reached a terminal-success status (`succeeded` or `failed`); a job that already completed cannot be cancelled.

Exemple de requête et de réponse

Requête

curl -X DELETE https://api.knogin.com/v1/jobs/01HFXY... \
  -H "Authorization: Bearer $TOKEN"

Réponse

HTTP/1.1 204 No Content

GET

/v1/jobs

List jobs

Lists jobs for the caller's tenant with optional kind and status filters and cursor pagination.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:jobs:read` scope on a bearer token.
Supports filters `kind` (one of the supported job kinds) and `status` (any value from the status enum).
Pagination uses `limit` (default 50, max 200) and an opaque `cursor` token returned as `next_cursor` on the previous page.
Results are scoped to the caller's tenant; cross-tenant rows are never returned.

Exemple de requête et de réponse

Requête

curl "https://api.knogin.com/v1/jobs?kind=intelligence.enrich.bulk&status=running&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Réponse

{
  "jobs": [
    {
      "id": "01HFXY...",
      "kind": "intelligence.enrich.bulk",
      "status": "running",
      "progress_pct": 42,
      "created_at": "2026-05-08T12:00:00Z",
      "trace_id": "0af7651916cd43dd8448eb211c80319c"
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiLi4uIn0=",
  "total_count": 1234
}

Contrat public

Sandbox environment

Issue short-lived sandbox tokens (aud=sandbox) and route the entire v2026.4 surface to deterministic mock connectors at https://sandbox-api.knogin.com. Dual gate prevents leak between sandbox and live.

POST

/v1/platform/apps/{client_id}/sandbox-token

Issue a sandbox token

Mints a short-lived sandbox token (aud=sandbox) for the requested app. Sandbox tokens route to deterministic mock connectors at https://sandbox-api.knogin.com.

Host: https://auth.knogin.com
Auth: Bearer token
Audience: Admins client
Stabilité: Stable

Requires the `argus:platform:admin` scope to mint sandbox tokens. Sandbox tokens themselves cannot mint further sandbox tokens.
`ttl_seconds` is clamped to the inclusive range [60, 86400]; values outside are normalised before signing.
Optional `scenarios` array pins the sandbox to specific scenario IDs so the same client_id consistently sees the same canned data.
The returned token carries `aud=sandbox`. Use it against the sandbox host `https://sandbox-api.knogin.com`; live hosts reject sandbox tokens with 403.
Sandbox tokens carry the issuing tenant's `tenant_id` and `organization_id` so audit and rate-limiting remain tenant-scoped.

Exemple de requête et de réponse

Requête

curl -X POST https://auth.knogin.com/v1/platform/apps/app_123/sandbox-token \
  -H "Authorization: Bearer <admin-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scenarios": ["wallet.high-risk", "entity.sanctioned"],
    "ttl_seconds": 3600
  }'

Réponse

{
  "token": "<sandbox-jwt>",
  "expires_at": "2026-05-08T13:00:00Z",
  "audience": "sandbox",
  "scopes": ["argus:profiles:read", "argus:profiles:write", "argus:jobs:read", "argus:jobs:write"],
  "sandbox_host": "https://sandbox-api.knogin.com",
  "scenarios": ["wallet.high-risk", "entity.sanctioned"]
}

GET

/v1/sandbox/scenarios

List sandbox scenarios

Returns the deterministic scenario catalogue (wallet.high-risk, wallet.clean, entity.sanctioned, incident.escalating, device.offline) available on the sandbox host.

Host: https://sandbox-api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires a sandbox token (`aud=sandbox`); a live token returns 403.
Hosted on `https://sandbox-api.knogin.com`; calling the same path on the live API host returns 404.
Scenario IDs returned by this endpoint are the canonical values accepted by the `scenarios` field on `POST /v1/platform/apps/{client_id}/sandbox-token`.
Sandbox responses also carry `X-Argus-Sandbox: true` so partner debugging tools see at a glance that the response is synthetic.

Exemple de requête et de réponse

Requête

curl https://sandbox-api.knogin.com/v1/sandbox/scenarios \
  -H "Authorization: Bearer <sandbox-token>"

Réponse

{
  "scenarios": [
    {
      "id": "wallet.high-risk",
      "label": "High-risk wallet",
      "description": "Returns enrichment indicating sanctions hits, mixer interaction, and high-volume rapid-fire transfers."
    },
    {
      "id": "wallet.clean",
      "label": "Clean wallet",
      "description": "Returns enrichment indicating low-risk activity, no sanctions hits."
    },
    {
      "id": "entity.sanctioned",
      "label": "Sanctioned entity",
      "description": "Returns OSINT enrichment with OFAC/UN/EU sanctions matches."
    },
    {
      "id": "incident.escalating",
      "label": "Escalating incident",
      "description": "Returns dispatch / ePCR signals consistent with a worsening situation."
    },
    {
      "id": "device.offline",
      "label": "Offline medical device",
      "description": "Returns telemetry indicating last-seen N hours ago with stale battery state."
    }
  ]
}

Contrat public

Discovery and governance

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.

GET

/.well-known/openapi.json

Fetch the OpenAPI well-known descriptor (JSON)

Returns the curated public OpenAPI 3.1 contract at the RFC 8615 well-known path. No authentication required.

Host: https://api.knogin.com
Auth: Public
Audience: Intégrateurs externes
Stabilité: Stable

RFC 8615 well-known URI: tooling can locate the OpenAPI descriptor without bespoke configuration.
Content-Type `application/json`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.
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.
Response is identical to `openapi.yaml` in semantic content; only the serialisation differs.

Exemple de requête et de réponse

Requête

curl https://api.knogin.com/.well-known/openapi.json

Réponse

{
  "openapi": "3.1.0",
  "info": {
    "title": "Argus External API",
    "version": "2026.4.0"
  },
  "paths": { "/v1/jobs": { "...": "..." } }
}

GET

/.well-known/openapi.yaml

Fetch the OpenAPI well-known descriptor (YAML)

Returns the same curated public OpenAPI 3.1 contract as YAML at the RFC 8615 well-known path. No authentication required.

Host: https://api.knogin.com
Auth: Public
Audience: Intégrateurs externes
Stabilité: Stable

RFC 8615 well-known URI: tooling that prefers YAML can locate the OpenAPI descriptor without bespoke configuration.
Content-Type `application/yaml`. ETag is derived from the content hash; `304 Not Modified` is returned for matching `If-None-Match`.
Semantic content is identical to `openapi.json`; the same denylist filtering applies.

Exemple de requête et de réponse

Requête

curl https://api.knogin.com/.well-known/openapi.yaml

Réponse

openapi: 3.1.0
info:
  title: Argus External API
  version: 2026.4.0
paths:
  /v1/jobs:
    get: { ... }

GET

/.well-known/api-catalog

Fetch the API catalog link-set

Returns the RFC 9727 link-set pointing at the OpenAPI descriptors and the published documentation site. No authentication required.

Host: https://api.knogin.com
Auth: Public
Audience: Intégrateurs externes
Stabilité: Stable

RFC 9727 link-set format: a single `linkset` array of `{ anchor, service-desc, service-doc }` objects.
The `service-desc` entries advertise both the JSON and YAML OpenAPI well-known URIs.
Partner-only service metadata is intentionally excluded from the public catalog.
Content-Type `application/linkset+json`.

Exemple de requête et de réponse

Requête

curl https://api.knogin.com/.well-known/api-catalog

Réponse

{
  "linkset": [
    {
      "anchor": "https://api.knogin.com/",
      "service-desc": [
        { "href": "https://api.knogin.com/.well-known/openapi.json", "type": "application/json" },
        { "href": "https://api.knogin.com/.well-known/openapi.yaml", "type": "application/yaml" }
      ],
      "service-doc": [
        { "href": "https://knogin.com/en/docs/api-reference", "type": "text/html" }
      ]
    }
  ]
}

GET

/v1/discovery/data-schemas

List visible data schemas for the caller

Reflective endpoint listing the JSON schemas the caller's tenant and clearance can reach right now, with optional COI federation.

Host: https://api.knogin.com
Auth: Bearer token
Audience: Intégrateurs externes
Stabilité: Stable

Requires the `argus:discovery:read` scope on a bearer token.
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.
Optional query parameter `include_federated=true` extends the listing with upstream sources reachable via approved Communities of Interest (COI) channels.
Optional query parameter `secrecy_max=` clamps results to a clearance level; the default is the caller's own clearance.
Each schema entry advertises its canonical `schema_url` under `/.well-known/schemas/{id}.json` for offline contract pinning.
Audit event `discovery.schemas.read` is emitted on every call.

Exemple de requête et de réponse

Requête

curl "https://api.knogin.com/v1/discovery/data-schemas?include_federated=true" \
  -H "Authorization: Bearer $TOKEN"

Réponse

{
  "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": []
}

Besoin d’accéder à des intégrations avancées ?

Utilisez la demande d’intégration pour des bundles GraphQL curés, des APIs avancées de plateforme, la fédération d’entreprise ou un sandbox.