Versioning & deprecation

The API is versioned in the URL path. This page sets out what we consider a breaking change, what we can change without warning, and how to write a client that survives both.

The current version

Every endpoint lives under /api/v1/:

curl https://api.ospulse.app/api/v1/packages \
  -H "Authorization: Bearer $OSPULSE_TOKEN"

There is no version header and no per-request version negotiation. The path segment is the whole story — which means the version you integrate against is visible in every line of your code and every log entry.

You can confirm what you are talking to at any time:

curl https://api.ospulse.app/api/v1/version

{
  "product": "OSPulse",
  "version": "0.1.0.0",
  "buildId": "local",
  "gitSha": "unknown",
  "commitDate": "unknown",
  "environment": "Production"
}

What counts as a breaking change

A breaking change is anything that could stop a correctly-written existing client from working. We will not make these within v1:

• Removing an endpoint, or changing its HTTP method or path
• Removing a field from a response, or renaming one
• Changing the type of an existing field, or its meaning
• Adding a new required request parameter or body field
• Making validation stricter on input that was previously accepted
• Changing the success status code an endpoint returns
• Removing a value from an enum that responses already return

If we need to do any of these, it will happen in a new version — /api/v2/ — and v1 will continue to be served through the deprecation process below.

What we may change at any time

These are not breaking changes, and your client must tolerate them:

• Adding a new endpoint.
• Adding a new field to a response. Never assume you have seen the complete object.
• Adding a new optional request parameter.
• Adding a new value to an enum. New alert kinds, ecosystems, scan states, and severity levels appear as the platform grows.
• Changing the order of items in a collection where no order is guaranteed.
• Changing human-readable text — the detail string on an error, a description field. Never parse these; branch on status and machine-readable codes instead.
• Performance and pagination internals, including how totalEstimate is computed.

Writing a forward-compatible client

// System.Text.Json ignores unknown members by default — keep it that way.
var options = new JsonSerializerOptions
{
    PropertyNameCaseInsensitive = true,
    // Do NOT set UnmappedMemberHandling.Disallow
};

const KNOWN_SEVERITIES = ['low', 'medium', 'high', 'critical']
 
function isBlocking(severity) {
  // An unfamiliar severity is treated as significant rather than ignored.
  if (!KNOWN_SEVERITIES.includes(severity)) return true
  return severity === 'high' || severity === 'critical'
}

Deprecation policy

When something must be retired, we follow a predictable sequence rather than removing it abruptly.

If a new major version arrives

A v2 would be introduced alongside v1, not in place of it. You would be able to migrate endpoint by endpoint, because the path prefix is per-request — nothing forces an all-at-once cutover. v1 would remain available throughout the announced support window.

Next steps