Guides Reference

API contract and stability

This guide explains what the CyberSentriq API promises, so you know what your integration can depend on and how you will hear about change before it affects you.

The published contract

The contract is https://api.cybersentriq.com/openapi.json, which the API reference renders. It describes every endpoint that is generally available today, with its parameters, request and response schemas, and required permissions.

The published contract is a faithful subset of the wider platform API: it lists only what is generally available and stable, and everything it lists behaves as described. More of the platform surface opens up over time, and endpoints join the published contract as they become generally available.

Versioning

Endpoints are versioned with an api-version query parameter. Pin it in production clients so a new default version cannot change your integration's behavior. See Endpoints you call for the mechanics.

What we can change without notice

These changes are backwards-compatible, so they can land at any time. Build your client to tolerate them:

  • new endpoints, and new optional parameters on an existing endpoint;
  • new fields in a response;
  • new permissions in the catalog.

Decode responses leniently: ignore fields you do not recognize rather than failing on them.

What we announce before changing

These changes can break a client, so they are versioned and announced ahead of time, never applied silently:

  • removing or renaming a field, endpoint or permission;
  • changing the type or meaning of an existing field;
  • making a previously optional input required.

Deprecation notices, a change log and machine-readable sunset dates are being rolled out. Declare what you rely on (below) so you are notified directly in the meantime.

Tell us what you rely on

You do not have to watch for changes. Use the Declare reliance control on any endpoint in the reference to record the endpoint, field or permission your integration depends on. We use those declarations to notify you before we change or retire anything you rely on, and you can review and manage them from your account.

This is the most reliable way to stay ahead of change: a declaration ties a specific part of the contract to you, so a notice reaches you directly rather than only appearing in a change log.

Permissions are part of the contract

What each endpoint requires is part of the contract too: the reference states the required permission on every endpoint, and the catalog of permissions is documented. See Permissions.

Next