API overview

The OSPulse API is a JSON REST API served from https://api.ospulse.app. Every operation documented here is generated from the same OpenAPI 3.0.1 description the service publishes — 246 operations across 360 schemas — so the reference and the running API cannot drift apart.

Base URL and versioning

All production traffic goes to a single host over HTTPS. Plain HTTP is not served; requests to http:// are rejected rather than redirected, so a downgraded request never leaks a token.

A full URL is therefore the base, the version prefix, and the resource path:

https://api.ospulse.app/api/v1/packages
└──────── base ────────┘└─ prefix ─┘└ path ┘

Two surfaces sit outside the /api/v1/ prefix by design, because their paths are fixed by external standards or by consumers that predate the version prefix:

See Versioning for what counts as a breaking change and how new versions are introduced.

Authentication

Every endpoint except the health, version, and public status endpoints requires a bearer token in the Authorization header:

Authorization: Bearer {token}

Tokens are created in the app under API tokens in the main navigation (app.ospulse.app/api-tokens, administrators only), or through the API itself with POST /api/v1/api-tokens. List them with GET /api/v1/api-tokens and revoke one with DELETE /api/v1/api-tokens/{apiTokenId}. A token is scoped to the tenant that created it — there is no cross-tenant token, and no tenant identifier is sent on the request.

Full detail, including scoping, expiry, and rotation, is in Authentication.

Content types

Requests that send a body without a JSON content type are rejected with 415. Bodies that are syntactically valid JSON but semantically invalid return 400 or 422 — see Errors.

Your first call

The health endpoint needs no credentials, so it is the fastest way to confirm connectivity before you introduce a token into the equation.

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

Then make an authenticated request. This lists the packages OSPulse tracks for your tenant, five at a time:

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

Collection endpoints return a page envelope rather than a bare array, so the paging state travels with the data. Note the counter field differs between endpoints — this one reports totalReturned, the size of this page, while most collections report an approximate totalEstimate:

{
  "items": [
    {
      "packageId": "9d3f7c21-8a4b-4e15-b6c0-3f8e2a91d574",
      "name": "express",
      "ecosystem": "Npm",
      "latestVersion": "4.21.2",
      "status": "Active",
      "sourceRepositoryUrl": "https://github.com/expressjs/express"
    }
  ],
  "take": 5,
  "skip": 0,
  "totalReturned": 5
}

See Pagination for the full envelope and an iteration loop.

Resource groups

Endpoints are grouped by the domain object they act on. Each group below links to its area of the interactive reference, where the exact parameters, schemas, and status codes are listed.

Several smaller groups round out the surface: /api/v1/ai/* for generated summaries, remediation advice, and natural-language queries; /api/v1/health and /api/v1/version for liveness; /api/v1/onboarding, /api/v1/feature-flags, /api/v1/settings/retention, and /api/v1/cli-version for account and client plumbing; and /api/v1/ide/verdicts:batch for editor integrations.

How this reference is produced

The service emits its OpenAPI description at build time from the same route definitions, request models, and response models that handle live traffic. That document is published at /openapi.json and rendered into the interactive reference.

Consequences worth knowing:

• The spec is the source of truth. If a prose page here and the interactive reference disagree, the reference is correct — tell us so we can fix the prose.
• Schemas are complete. Every request and response body has a named schema in the document, so client generators produce usable types without hand-editing.
• The servers block is not the production URL. The generated document carries a local development server entry. Point generated clients at https://api.ospulse.app explicitly.

Reading the rest of the reference

Next steps