Conventions

Rules that hold across the whole OSPulse API. Learn them once and every endpoint in the reference becomes predictable — field naming, timestamp format, identifier shape, enum behaviour, and what each HTTP verb is allowed to do.

Transport

Content type

Every request that carries a body must declare it:

Content-Type: application/json

Responses are application/json, with one deliberate exception: error responses follow RFC 7807 problem details and may be served as application/problem+json. Parse them as JSON either way.

Endpoints that accept file uploads — SBOM upload, for example — take multipart/form-data instead, and are marked as such in the reference. Sending an unsupported media type returns 415 Unsupported Media Type.

Download endpoints (generated reports, SBOM exports, evidence packs, CBOM documents) stream the artefact with its own content type. Do not assume JSON from a path ending in /download.

Field naming

Path parameters are documented in the reference in brace form — {repositoryId}, {packageId}, {scanId} — and are substituted literally, with no braces in the request.

Dates and times

Every timestamp is ISO-8601 in UTC. Fields carrying an instant are suffixed Utc so the timezone is unambiguous from the name alone: capturedAtUtc, expiresAtUtc, sinceUtc.

{
  "snapshotId": "8f0c2f66-3d3c-4c1f-9a2f-4b1c6d0f2f11",
  "capturedAtUtc": "2026-03-14T09:21:47.482Z"
}

Identifiers

Resource identifiers are GUIDs (UUIDs) rendered as lowercase, hyphenated, 36-character strings. They appear in path parameters, in request bodies, and as …Id fields in responses.

/api/v1/repositories/3f8a1c27-9c1b-4e2a-8f6d-2a7c5e9b0d14/dependencies

Two identifiers are not GUIDs and should not be treated as such: SCIM resource ids under /scim/v2/, which follow the SCIM specification, and vulnerability identifiers such as CVE-2025-12345, which are external catalogue keys.

Null versus omitted

Many response fields are nullable. A field may therefore appear in three ways, and they mean different things:

In requests the distinction matters more, because PATCH bodies are partial:

• Omit a field to leave the stored value untouched.
• Send null to clear a nullable field.
• Send a value to replace it.

Enumerations

Enum values are transmitted as strings in PascalCase — Npm, Healthy, Critical — not as integers. String values keep responses readable and let new members be added without renumbering.

{
  "ecosystem": "Npm",
  "riskLevel": "High",
  "state": "Completed"
}

New enum members are added over time: a new ecosystem, a new workflow state, a new severity band. Adding a member is not treated as a breaking change, so your client must tolerate values it has never seen.

Correlation identifiers

Error responses carry a correlationId — a GUID identifying the exact request as it passed through the service.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An unexpected error occurred.",
  "status": 500,
  "detail": "The request could not be completed.",
  "instance": "/api/v1/repositories/3f8a1c27-9c1b-4e2a-8f6d-2a7c5e9b0d14/scan",
  "correlationId": "9d1a7f42-6b0e-4c3a-a7f1-2c5d8e0b3f96"
}

Log it on every non-2xx response, alongside the method, path, and status. It is the single most useful thing you can give support: with a correlationId we can find your request in the service logs directly, rather than guessing from a timestamp. Without one, diagnosing an intermittent failure is guesswork.

HTTP verb semantics

GET, PUT, PATCH, and DELETE are idempotent: sending the same request twice leaves the system in the same state as sending it once. POST is not, which is why retry strategy differs for it — see Errors.

Action endpoints

Operations that are neither pure reads nor plain resource creation are expressed as a POST to a named sub-resource, sometimes with a colon-prefixed verb:

POST /api/v1/repositories/{repositoryId}/scan
POST /api/v1/scans/{scanId}/cancel
POST /api/v1/policies/{policyId}/test
POST /api/v1/quantum/probe-endpoints/{endpointId}:verify
POST /api/v1/analytics/export/destinations/{id}:run

The colon form marks an action on the addressed resource rather than a child collection. It is still an ordinary POST — no special encoding, no special headers.

Asynchronous operations

Work that cannot complete inside a request returns 202 Accepted with an identifier, and you poll a companion GET for the result. Scans, SBOM imports and exports, report generation, evidence archives, quarterly summaries, and warehouse export runs all behave this way.

{
  "scanId": "c41d9b8e-7a52-4f0d-9b3e-1d6a2f7c8e40",
  "state": "Queued"
}

Poll the corresponding detail endpoint — GET /api/v1/scans/{scanId} in this case — until the state reaches a terminal value. Poll on an interval measured in seconds, not milliseconds, and back off as the wait lengthens. Downloading the output of a job that has not finished returns 409 Conflict.

Request headers

Unrecognised headers are ignored. No custom X- header is required to call the API.

Next steps