Knogin
[Contratto pubblico curato]

API di Integrazione Esterna

Questa pagina documenta solo il contratto stabile di integrazione esterna. È volutamente limitata agli endpoint e alle garanzie di trasporto necessari agli integratori approvati.

Docs machine-readableRichiedi accesso avanzato

Confine di sicurezza

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.

Nomi delle rotte, esempi di token e dettagli di trasporto restano in inglese canonico per allinearsi esattamente al contratto pubblico.

Verifica JWTOAuth e service tokenWebhookSolo trasporto GraphQLNessun dump di schemaNessuna rotta interna

URL base

Servizio auth
https://auth.knogin.com
Trasporto GraphQL
https://api.knogin.com/graphql
Docs machine-readable
https://knogin.com/api/docs
Contratto pubblico

Identità e registrazione app

Registra un’integrazione, consulta gli scope approvati e gestisci la governance di un’app esterna.

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Register a named app before attempting OAuth authorization code or client credentials flows.
  • The response includes client metadata, approved grants, and tenancy context.
Esempio di request e response

Request

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"]
  }'

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Use this endpoint to audit redirect URIs, grants, and scope posture before rotating secrets or enabling new workflows.
Esempio di request e response

Request

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

Response

{
  "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
Admin cliente
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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
  }'

Response

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

OAuth e service token

Usa flussi di token approvati per integrazioni user-delegated o 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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

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
Integratori esterni
Stabilità
Stabile
  • Use authorization code for user-delegated access and client credentials for headless service integrations.
  • Only request scopes that were approved during app registration.
Esempio di request e response

Request

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"

Response

{
  "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
Admin cliente
Stabilità
Stabile
  • Service tokens are appropriate for webhook management, scheduled exports, and other machine-to-machine workflows.
  • Keep service-token issuance behind tenant admin approval.
Esempio di request e response

Request

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"]
  }'

Response

{
  "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
Admin cliente
Stabilità
Stabile
  • Treat the rotated secret as write-once material and replace it in your secret store immediately.
  • Rotate secrets before revoking old credentials from automation.
Esempio di request e response

Request

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

Response

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

JWKS e verifica token

Verifica i JWT emessi da Knogin contro chiavi pubbliche.

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Use this variant when your API client standardizes on versioned endpoints.
Esempio di request e response

Request

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

Response

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

Consegna eventi e webhook

Crea, testa e osserva consegne webhook in uscita per integrazioni approvate.

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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>"
  }'

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Use update operations to rotate secrets or adjust event selections without recreating the subscription.
Esempio di request e response

Request

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"]
  }'

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Use delivery history instead of internal logs to diagnose receiver behavior.
  • Delivery metadata is limited to the webhook in scope.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • Use test deliveries when rotating secrets or validating a new endpoint.
Esempio di request e response

Request

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

Response

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

Contratto di trasporto GraphQL

Connettiti al trasporto GraphQL condiviso senza pubblicare schema o inventario operazioni.

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "data": {
    "result": "Returned for your approved operation bundle"
  }
}
GET
/api/v1/epcr/encounters/{encounterId}

Fetch an ePCR encounter

Retrieve the partner-facing summary of an electronic patient care record encounter, or a FHIR R4 Bundle when ?format=fhir.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Partners receive a de-identified projection; full PII (DOB, NOK contact, street address) remain internal.
  • Pass ?format=fhir for an interoperability-ready FHIR R4 transaction Bundle.
Esempio di request e response

Request

curl https://api.knogin.com/api/v1/epcr/encounters/enc_123 \
  -H "Authorization: Bearer <access-token>"

Response

{
  "id": "enc_123",
  "organization_id": "org_1",
  "care_model": "prehospital_emergency",
  "status": "in_progress"
}
GET
/api/v1/epcr/encounters/{encounterId}/fhir-bundle

Export encounter as FHIR R4 Bundle

Return a FHIR R4 transaction Bundle for an ePCR encounter, suitable for handover into hospital EHRs.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Bundle contains Patient, Encounter, Observation, Procedure, MedicationAdministration, and Composition resources.
Esempio di request e response

Request

curl https://api.knogin.com/api/v1/epcr/encounters/enc_123/fhir-bundle \
  -H "Authorization: Bearer <access-token>"

Response

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": []
}
POST
/api/v1/epcr/encounters

Create an ePCR encounter

Create a new ePCR encounter from an external CAD-to-ePCR integration, scoped to the caller's organisation.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Requires the argus:epcr:write scope on the calling service token.
Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/epcr/encounters \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "care_model": "prehospital_emergency",
    "vehicle_id": "AMB-42",
    "crew_ids": ["usr_1"],
    "cad_incident_id": "cad_999"
  }'

Response

{
  "id": "enc_123",
  "status": "in_progress"
}
GET
/api/v1/devices

List medical devices

List IEEE 11073 PHD-enrolled medical devices for the caller's organisation, optionally filtered by vehicle.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Supported device classes: defib, ecg, oximeter, bp, glucose, etco2, thermometer, multiparameter.
Esempio di request e response

Request

curl "https://api.knogin.com/api/v1/devices?vehicle_id=AMB-42" \
  -H "Authorization: Bearer <access-token>"

Response

[
  {
    "id": "dev_1",
    "serial_number": "SN-0001",
    "device_class": "defib",
    "status": "active"
  }
]
POST
/api/v1/devices/enrol

Enrol a medical device

Enrol (or re-enrol) a medical device for this organisation so it can emit IEEE 11073 PHD observations.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Requires the argus:devices:write scope on the calling service token.
Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/devices/enrol \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-0001",
    "device_class": "defib",
    "manufacturer": "ACME"
  }'

Response

{
  "id": "dev_1",
  "serial_number": "SN-0001",
  "device_class": "defib",
  "status": "active"
}
POST
/api/v1/devices/{deviceId}/observations

Submit a PHD observation

Submit a single IEEE 11073 PHD observation (MDC metric code + UCUM unit) from an enrolled device.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Use mdc_code from ISO/IEEE 11073-10101 and unit_code from UCUM.
  • Optionally link the observation to an ePCR encounter via encounter_id.
Esempio di request e response

Request

curl -X POST https://api.knogin.com/api/v1/devices/dev_1/observations \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mdc_code": "MDC_PULS_OXIM_SAT_O2",
    "value": 98.0,
    "unit_code": "%"
  }'

Response

{
  "id": "obs_1",
  "device_id": "dev_1",
  "mdc_code": "MDC_PULS_OXIM_SAT_O2",
  "value": 98.0,
  "unit_code": "%"
}
query acqiMetrics(fromDate, toDate)

Query ACQI metrics

Retrieve Ambulance Clinical Quality Indicator metrics with sparkline trend data over a date range (GraphQL).

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Requires the argus:acqi:read scope on the calling service token.
Esempio di request e response

Request

curl -X POST https://api.knogin.com/graphql \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query($from: DateTime!, $to: DateTime!) { acqiMetrics(fromDate: $from, toDate: $to) { name value numerator denominator unit } }",
    "variables": { "from": "2026-04-01T00:00:00Z", "to": "2026-04-17T00:00:00Z" }
  }'

Response

{
  "data": {
    "acqiMetrics": [
      {
        "name": "rosc_survival",
        "value": 0.32
      }
    ]
  }
}
Disponibile su richiesta

Telephony provider configuration

Manage pluggable telephony providers and DID routing rules. Supported carriers: VoIP.ms, Twilio, Telnyx, Plivo, Bandwidth, generic SIP/IAX2 via gateway. Requires the argus:telephony:write scope.

query telephonyProviders(tenantId)

List telephony providers

Returns all configured telephony providers for a tenant, including carrier type, default flag, and active status. Credentials are never returned.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Partner strategici
Stabilità
Stabile
  • Requires the argus:telephony:read scope.
  • credentials_enc is never returned - the field is excluded from the external contract.
  • Added in contract v2026.2.
La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.
Richiedi accesso
query telephonyRoutes(tenantId, providerId)

List telephony routes (DID routing)

Returns all DID routing rules for a tenant, mapping phone numbers or provider subaccounts to a target subsystem (psap, municipal, utilities, etc.).

Host
https://api.knogin.com
Auth
Bearer token
Audience
Partner strategici
Stabilità
Stabile
  • Requires the argus:telephony:read scope.
  • Added in contract v2026.2.
La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.
Richiedi accesso
Contratto pubblico

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

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

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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"
  }'

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
}
Contratto pubblico

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
Admin cliente
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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
  }'

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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."
    }
  ]
}
Contratto pubblico

Provenance and compliance

Signed Merkle-chained transcripts of every evidence operation. Fetch as JSON or PROV-O JSON-LD, verify server-side or offline in the SDK, and present as a chain of custody for legal proceedings. HMAC-SHA256 default with ML-DSA-65 (post-quantum) opt-in.

GET
/v1/evidence/{evidence_id}/provenance

Get evidence provenance transcript

Returns the full Merkle-chained provenance transcript for an evidence record as JSON (default) or PROV-O JSON-LD. HMAC-SHA256 by default; ML-DSA-65 (post-quantum) opt-in via ?algorithm=ml-dsa-65.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Requires the `argus:provenance:read` scope on a bearer token.
  • Query parameter `format` accepts `json` (default) or `jsonld`. The `jsonld` variant emits a PROV-O document with `@context: https://www.w3.org/ns/prov` and standard term mapping (`prov:Activity`, `prov:wasGeneratedBy`, `prov:wasDerivedFrom`, `prov:Entity`, `prov:Agent`).
  • Query parameter `algorithm` accepts `hmac-sha256` (default, tenant-scoped HKDF-derived secret) or `ml-dsa-65` (post-quantum, via the existing pqc_adapter). The chosen algorithm is signed into both the per-record signatures and the Merkle root signature.
  • Each record carries `parent_id` and `parent_hash` so the transcript forms an append-only chain per `evidence_id`. The Merkle root binds the full ordered set of records and is signed independently.
  • Standard G2 trace headers are emitted; `trace_id` for each record is also captured inside the transcript for end-to-end correlation across the audit log.
  • Tenant scoped: cross-tenant lookups return 404 (never 403). SecrecyLevel of the underlying evidence applies: operators below the evidence's secrecy level cannot read its provenance.
Esempio di request e response

Request

curl "https://api.knogin.com/v1/evidence/ev_abc123/provenance?format=jsonld&algorithm=ml-dsa-65" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "evidence_id": "ev_abc123",
  "tenant_id": "tnt_123",
  "records": [
    {
      "id": "01HFXY...",
      "operation": "evidence.create",
      "actor_id": "user_42",
      "actor_kind": "user",
      "content_hash": "sha256:b94d...",
      "parent_hash": null,
      "signature": "<hex>",
      "signature_alg": "hmac-sha256",
      "signed_at": "2026-05-08T10:00:00Z",
      "trace_id": "0af7651916cd43dd8448eb211c80319c",
      "job_id": null
    }
  ],
  "merkle_root": "sha256:...",
  "root_signature": "<hex>",
  "root_signature_alg": "hmac-sha256",
  "format": "json",
  "version": "2026.4"
}
POST
/v1/evidence/{evidence_id}/provenance/verify

Verify a provenance transcript

Server-side verification of a provenance transcript: recomputes per-record content hashes, verifies signatures, and confirms the Merkle root. Returns broken_links if any record fails the signature or content-hash check.

Host
https://api.knogin.com
Auth
Bearer token
Audience
Integratori esterni
Stabilità
Stabile
  • Requires the `argus:provenance:read` scope on a bearer token.
  • Request body: `{ "transcript": <transcript object> }` where the transcript matches the shape returned by `GET /v1/evidence/{evidence_id}/provenance`.
  • Server-side verification is the canonical path. SDKs additionally ship an offline verify helper that needs no network round-trip: `evidence.verifyProvenanceLocal(transcript)` (TypeScript) and `evidence.verify_provenance_local(transcript)` (Python). The offline helper requires the published verify keys from `GET /v1/.well-known/provenance-keys/{algorithm}` for `ml-dsa-65`; HMAC verification stays server-side because the secret is tenant-scoped.
  • Returns 200 with `{ valid: true, checked_records, merkle_root_verified: true, broken_links: [] }` when the transcript is intact, or 200 with `valid: false`, `merkle_root_verified: false`, and a populated `broken_links` array when any record fails. The endpoint never returns 4xx for a tampered-but-well-formed transcript: 400 is reserved for malformed input.
  • Tenant scoped: cross-tenant verify returns 404. The audit entry includes `metadata = { record_count, format, algorithm, valid }`.
Esempio di request e response

Request

curl -X POST https://api.knogin.com/v1/evidence/ev_abc123/provenance/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": { "...": "<full transcript object from GET /provenance>" }
  }'

Response

{
  "valid": true,
  "evidence_id": "ev_abc123",
  "broken_links": [],
  "checked_records": 5,
  "merkle_root_verified": true
}
GET
/.well-known/provenance-keys/{algorithm}

Fetch a provenance verify key

Returns the public verify key for the given signature algorithm so that integrators can verify provenance transcripts offline. HMAC-SHA256 returns 404 because its secret is tenant-scoped; ML-DSA-65 returns the public verify key.

Host
https://api.knogin.com
Auth
Public
Audience
Integratori esterni
Stabilità
Stabile
  • Public endpoint: no bearer token required. The endpoint exposes only public key material; no tenant or signer identity is leaked.
  • Path parameter `algorithm` accepts `hmac-sha256` (always returns 404 because HMAC keys are tenant-scoped HKDF-derived secrets and cannot be exposed publicly) or `ml-dsa-65` (returns the public verify key that pairs with the platform-level ML-DSA-65 signer).
  • The response shape mirrors the well-known JWKS pattern: a `keys` array with `{ kid, alg, public_key }` entries. Cache responses with the same policy as JWKS and refresh on unknown `kid` values.
  • Use this endpoint only for offline verification. Server-side `POST /v1/evidence/{evidence_id}/provenance/verify` remains the canonical authoritative check.
Esempio di request e response

Request

curl https://api.knogin.com/v1/.well-known/provenance-keys/ml-dsa-65

Response

{
  "keys": [
    {
      "kid": "prov-2026-05-mldsa",
      "alg": "ml-dsa-65",
      "public_key": "<base64 ML-DSA-65 public key>"
    }
  ]
}
Contratto pubblico

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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

{
  "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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

Response

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, the published documentation site, and the provenance verify-key well-known. No authentication required.

Host
https://api.knogin.com
Auth
Public
Audience
Integratori esterni
Stabilità
Stabile
  • RFC 9727 link-set format: a single `linkset` array of `{ anchor, service-desc, service-doc, service-meta }` objects.
  • The `service-desc` entries advertise both the JSON and YAML OpenAPI well-known URIs.
  • 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.
  • Content-Type `application/linkset+json`.
Esempio di request e response

Request

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

Response

{
  "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" }
      ],
      "service-meta": [
        { "href": "https://api.knogin.com/.well-known/provenance-keys/ml-dsa-65", "type": "application/json", "rel": "provenance-verify-keys" }
      ]
    }
  ]
}
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
Integratori esterni
Stabilità
Stabile
  • 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.
Esempio di request e response

Request

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

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": []
}
Disponibile su richiesta

Capacità avanzate su richiesta

API di piattaforma ampliate, bundle GraphQL curati e federazione restano dietro accesso revisionato.

/api/v1/platform/*

Platform control-plane APIs

Expanded control-plane workflows under /api/v1/platform are available only through approved partner or customer programs.

Host
https://api.knogin.com
Auth
Request access
Audience
Partner strategici
Stabilità
Approvato su richiesta
  • Public docs intentionally stop at a high-level capability description.
  • Examples include deployment packages, automations, agents, marketplace flows, and release operations.
La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.
Richiedi accesso
Curated GraphQL operations by approved workflow

Curated GraphQL operation bundles

Approved integrations can receive a narrow set of GraphQL operations derived from vetted FE2 workflows instead of full schema discovery.

Host
https://api.knogin.com
Auth
Request access
Audience
Partner strategici
Stabilità
Approvato su richiesta
  • Examples include incident webhook configuration flows and other explicitly approved bundles.
  • This is the mechanism for exposing integrations without publishing the full GraphQL schema.
La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.
Richiedi accesso
/v1/saml/*

Enterprise federation and SAML

Federation setup and SAML onboarding are handled through guided implementation rather than a self-serve public blueprint.

Host
https://auth.knogin.com
Auth
Request access
Audience
Admin cliente
Stabilità
Approvato su richiesta
  • Enterprise identity integrations require tenant-specific coordination and are not documented as an open public API.
La documentazione dettagliata di questa capacità è disponibile solo tramite il processo di integrazione revisionato.
Richiedi accesso

Hai bisogno di accesso a integrazioni avanzate?

Usa la richiesta di integrazione per bundle GraphQL curati, accesso alla piattaforma, federazione enterprise o sandbox onboarding.