Ingestion API patterns

Asynchronous ingestion jobs

Use job-oriented workflows for scanner imports: submit source payload, poll status, review normalized candidates, then finalize. Treat finalize as a privileged mutation gate that requires validated authority and policy-safe mapping state.

Pagination and filtering

• Support deterministic pagination for large scan and finding result sets.
• Provide stable filters for tenant, asset, target, scanner source, and lifecycle status.
• Return predictable metadata for page/limit/cursor semantics where applicable.
• Document defaults and bounds explicitly to prevent accidental unbounded queries.

Idempotency and safe retry

Scanner integrations should expect transient failures and rate-control behavior. Mutation endpoints should support idempotent request semantics where feasible and clients should implement bounded backoff/retry logic for non-terminal failures.

Ingestion response envelope

Use consistent success/error envelopes with machine-readable codes, stable job states, and non-sensitive human-readable messages. Internal diagnostics stay server-side and in tenant-scoped audit/telemetry channels.