{"id":"async-jobs","title":"Async jobs","description":"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.","lastUpdated":"2026-05-08","sections":[{"id":"jobs-enqueue","title":"POST /v1/jobs · Enqueue an async job","content":"Route: POST /v1/jobs\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreates an async job for one of the supported kinds and returns an `id` for polling or webhook delivery.\n\nIntegration notes:\n- Requires the `argus:jobs:write` scope on a bearer token.\n- Initial supported kinds: `intelligence.enrich.bulk`, `export.bulk`, `import.bulk`, `graph.compute`.\n- 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.\n- Optional `callback_url` enables a signed webhook delivery on completion; otherwise poll the status and result endpoints.","codeExamples":[{"language":"bash","code":"curl -X POST https://api.knogin.com/v1/jobs \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: 8b9d8a2e-4a8c-4a7e-8a2e-4a8c4a7e8a2e\" \\\n  -d '{\n    \"kind\": \"intelligence.enrich.bulk\",\n    \"payload\": { \"profile_ids\": [\"p1\", \"p2\"] },\n    \"callback_url\": \"https://partner.example.com/argus-webhook\",\n    \"secrecy_level\": \"standard\"\n  }'","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"01HFXY...\",\n  \"kind\": \"intelligence.enrich.bulk\",\n  \"status\": \"queued\",\n  \"created_at\": \"2026-05-08T12:00:00Z\",\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n}","description":"Response example"}]},{"id":"jobs-get","title":"GET /v1/jobs/{id} · Get job status","content":"Route: GET /v1/jobs/{id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the current state of a single job, including kind, status, progress, timestamps, error, and trace ID.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- `status` enum: `queued`, `running`, `succeeded`, `failed`, `cancelled`.\n- Cross-tenant lookups return 404 (never 403) to avoid revealing existence.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/v1/jobs/01HFXY... \\\n  -H \"Authorization: Bearer $TOKEN\"","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"01HFXY...\",\n  \"kind\": \"intelligence.enrich.bulk\",\n  \"status\": \"running\",\n  \"progress_pct\": 42,\n  \"created_at\": \"2026-05-08T12:00:00Z\",\n  \"updated_at\": \"2026-05-08T12:00:30Z\",\n  \"completed_at\": null,\n  \"error\": null,\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n}","description":"Response example"}]},{"id":"jobs-result","title":"GET /v1/jobs/{id}/result · Get job result","content":"Route: GET /v1/jobs/{id}/result\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the result reference and a short-lived signed URL once the job has succeeded.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- Returns 202 with `{ status, progress_pct }` while the job is still `queued` or `running`.\n- Returns 410 once the result has expired (default 30-day retention); the job record itself remains queryable.\n- The `signed_url` is a short-lived presigned URL into R2; treat it as a credential.","codeExamples":[{"language":"bash","code":"curl https://api.knogin.com/v1/jobs/01HFXY.../result \\\n  -H \"Authorization: Bearer $TOKEN\"","description":"Request example"},{"language":"json","code":"{\n  \"id\": \"01HFXY...\",\n  \"result_ref\": \"r2://argus-jobs/results/01HFXY.json\",\n  \"signed_url\": \"https://r2-presigned-url...\"\n}","description":"Response example"}]},{"id":"jobs-cancel","title":"DELETE /v1/jobs/{id} · Cancel a job","content":"Route: DELETE /v1/jobs/{id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRequests cancellation of a queued or running job. Idempotent replays of an already-cancelled job return 200.\n\nIntegration notes:\n- Requires the `argus:jobs:write` scope on a bearer token.\n- Returns 204 when a `queued` or `running` job is cancelled.\n- Returns 200 when the job is already `cancelled` (idempotent replay).\n- Returns 409 only when the job has reached a terminal-success status (`succeeded` or `failed`); a job that already completed cannot be cancelled.","codeExamples":[{"language":"bash","code":"curl -X DELETE https://api.knogin.com/v1/jobs/01HFXY... \\\n  -H \"Authorization: Bearer $TOKEN\"","description":"Request example"},{"language":"text","code":"HTTP/1.1 204 No Content","description":"Response example"}]},{"id":"jobs-list","title":"GET /v1/jobs · List jobs","content":"Route: GET /v1/jobs\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nLists jobs for the caller's tenant with optional kind and status filters and cursor pagination.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- Supports filters `kind` (one of the supported job kinds) and `status` (any value from the status enum).\n- Pagination uses `limit` (default 50, max 200) and an opaque `cursor` token returned as `next_cursor` on the previous page.\n- Results are scoped to the caller's tenant; cross-tenant rows are never returned.","codeExamples":[{"language":"bash","code":"curl \"https://api.knogin.com/v1/jobs?kind=intelligence.enrich.bulk&status=running&limit=50\" \\\n  -H \"Authorization: Bearer $TOKEN\"","description":"Request example"},{"language":"json","code":"{\n  \"jobs\": [\n    {\n      \"id\": \"01HFXY...\",\n      \"kind\": \"intelligence.enrich.bulk\",\n      \"status\": \"running\",\n      \"progress_pct\": 42,\n      \"created_at\": \"2026-05-08T12:00:00Z\",\n      \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n    }\n  ],\n  \"next_cursor\": \"eyJjcmVhdGVkX2F0IjoiLi4uIn0=\",\n  \"total_count\": 1234\n}","description":"Response example"}]}],"relatedTopics":["identity-app-registration","oauth-service-tokens","jwks-token-verification","event-delivery-webhooks","graphql-transport-contract","observability-and-tracing","sandbox-environment","provenance-and-compliance","discovery-and-governance"],"markdown":"# Async jobs\n\nEnqueue 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.\n\n## POST /v1/jobs · Enqueue an async job\n\nRoute: POST /v1/jobs\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nCreates an async job for one of the supported kinds and returns an `id` for polling or webhook delivery.\n\nIntegration notes:\n- Requires the `argus:jobs:write` scope on a bearer token.\n- Initial supported kinds: `intelligence.enrich.bulk`, `export.bulk`, `import.bulk`, `graph.compute`.\n- 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.\n- Optional `callback_url` enables a signed webhook delivery on completion; otherwise poll the status and result endpoints.\n\nRequest example\n\n```bash\ncurl -X POST https://api.knogin.com/v1/jobs \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: 8b9d8a2e-4a8c-4a7e-8a2e-4a8c4a7e8a2e\" \\\n  -d '{\n    \"kind\": \"intelligence.enrich.bulk\",\n    \"payload\": { \"profile_ids\": [\"p1\", \"p2\"] },\n    \"callback_url\": \"https://partner.example.com/argus-webhook\",\n    \"secrecy_level\": \"standard\"\n  }'\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"01HFXY...\",\n  \"kind\": \"intelligence.enrich.bulk\",\n  \"status\": \"queued\",\n  \"created_at\": \"2026-05-08T12:00:00Z\",\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n}\n```\n\n## GET /v1/jobs/{id} · Get job status\n\nRoute: GET /v1/jobs/{id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the current state of a single job, including kind, status, progress, timestamps, error, and trace ID.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- `status` enum: `queued`, `running`, `succeeded`, `failed`, `cancelled`.\n- Cross-tenant lookups return 404 (never 403) to avoid revealing existence.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/v1/jobs/01HFXY... \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"01HFXY...\",\n  \"kind\": \"intelligence.enrich.bulk\",\n  \"status\": \"running\",\n  \"progress_pct\": 42,\n  \"created_at\": \"2026-05-08T12:00:00Z\",\n  \"updated_at\": \"2026-05-08T12:00:30Z\",\n  \"completed_at\": null,\n  \"error\": null,\n  \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n}\n```\n\n## GET /v1/jobs/{id}/result · Get job result\n\nRoute: GET /v1/jobs/{id}/result\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nReturns the result reference and a short-lived signed URL once the job has succeeded.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- Returns 202 with `{ status, progress_pct }` while the job is still `queued` or `running`.\n- Returns 410 once the result has expired (default 30-day retention); the job record itself remains queryable.\n- The `signed_url` is a short-lived presigned URL into R2; treat it as a credential.\n\nRequest example\n\n```bash\ncurl https://api.knogin.com/v1/jobs/01HFXY.../result \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nResponse example\n\n```json\n{\n  \"id\": \"01HFXY...\",\n  \"result_ref\": \"r2://argus-jobs/results/01HFXY.json\",\n  \"signed_url\": \"https://r2-presigned-url...\"\n}\n```\n\n## DELETE /v1/jobs/{id} · Cancel a job\n\nRoute: DELETE /v1/jobs/{id}\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nRequests cancellation of a queued or running job. Idempotent replays of an already-cancelled job return 200.\n\nIntegration notes:\n- Requires the `argus:jobs:write` scope on a bearer token.\n- Returns 204 when a `queued` or `running` job is cancelled.\n- Returns 200 when the job is already `cancelled` (idempotent replay).\n- Returns 409 only when the job has reached a terminal-success status (`succeeded` or `failed`); a job that already completed cannot be cancelled.\n\nRequest example\n\n```bash\ncurl -X DELETE https://api.knogin.com/v1/jobs/01HFXY... \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nResponse example\n\n```text\nHTTP/1.1 204 No Content\n```\n\n## GET /v1/jobs · List jobs\n\nRoute: GET /v1/jobs\nHost: https://api.knogin.com\nAuth: Bearer token\nAudience: External integrators\nStability: Stable\n\nLists jobs for the caller's tenant with optional kind and status filters and cursor pagination.\n\nIntegration notes:\n- Requires the `argus:jobs:read` scope on a bearer token.\n- Supports filters `kind` (one of the supported job kinds) and `status` (any value from the status enum).\n- Pagination uses `limit` (default 50, max 200) and an opaque `cursor` token returned as `next_cursor` on the previous page.\n- Results are scoped to the caller's tenant; cross-tenant rows are never returned.\n\nRequest example\n\n```bash\ncurl \"https://api.knogin.com/v1/jobs?kind=intelligence.enrich.bulk&status=running&limit=50\" \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\nResponse example\n\n```json\n{\n  \"jobs\": [\n    {\n      \"id\": \"01HFXY...\",\n      \"kind\": \"intelligence.enrich.bulk\",\n      \"status\": \"running\",\n      \"progress_pct\": 42,\n      \"created_at\": \"2026-05-08T12:00:00Z\",\n      \"trace_id\": \"0af7651916cd43dd8448eb211c80319c\"\n    }\n  ],\n  \"next_cursor\": \"eyJjcmVhdGVkX2F0IjoiLi4uIn0=\",\n  \"total_count\": 1234\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- [Sandbox environment](https://knogin.com/api/docs/sandbox-environment)\n- [Provenance and compliance](https://knogin.com/api/docs/provenance-and-compliance)\n- [Discovery and governance](https://knogin.com/api/docs/discovery-and-governance)","metadata":{"readingTime":"10 min","difficulty":"intermediate","tags":["integrations","api","oauth","webhooks","graphql"]}}