OpenAPI specification

Every endpoint OSPulse exposes is described by a single OpenAPI document, published at https://ospulse.app/openapi.json. It is not a hand-maintained summary of the API — it is generated from the API itself, which makes it the authoritative contract and the thing you should build tooling against.

curl -sO https://ospulse.app/openapi.json

No authentication is required to fetch it.

What it covers

Getting your bearings

Before you generate anything, it is worth reading the shape of the document. A few jq queries answer most first questions:

# How many operations, and under which tags?
jq '[.paths[] | to_entries[]] | length' openapi.json
 
jq -r '[.paths[] | to_entries[].value.tags[0]] | group_by(.) | map("\(.[0])\t\(length)") | .[]' \
  openapi.json | sort
 
# Every path in one tag.
jq -r '.paths | to_entries[] | select(.value | to_entries[].value.tags[0] == "Packages") | .key' \
  openapi.json
 
# The exact shape of a response model.
jq '.components.schemas.PackageHealthResponse' openapi.json

The interactive reference is generated from it

Explore all endpoints is not written by hand — it renders this same document. That means the reference cannot drift from the API: when an endpoint gains a query parameter, the parameter appears in the reference on the next deploy, without anyone remembering to update prose.

It also means anything you can see in the reference, you can extract from the spec programmatically — request bodies, enum values, status codes, and descriptions all come from the same source.

Generate a client

The most common use of the spec is producing a typed client for your language. Full commands for TypeScript, Go, Java, C#, and Python are on the SDK overview; the short version:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i https://ospulse.app/openapi.json \
  -g typescript-fetch \
  -o /local/src/ospulse

Check the generation command into your repository — ideally as a script or a make target — so the client is reproducible rather than a one-off artefact whose provenance nobody remembers.

Run a mock server

A mock lets you build and test an integration before you have credentials, and lets your test suite run without touching production. Prism serves a mock directly from the spec, generating responses from the declared schemas:

npx @stoplight/prism-cli mock https://ospulse.app/openapi.json --port 4010

Point your client at it and every endpoint answers with schema-valid data:

curl -s http://127.0.0.1:4010/api/v1/packages?take=2 -H "Authorization: Bearer mock"

Prism can also run in proxy mode, forwarding to the real API while validating both the request you sent and the response you got against the contract. This is the fastest way to find out that you are sending a field the API does not accept:

npx @stoplight/prism-cli proxy openapi.json https://api.ospulse.app --errors

Contract testing

If your integration is load-bearing, assert against the contract in CI rather than hoping.

Schema-validate real responses. The cheapest useful test: call the endpoints you depend on and check the responses against the schemas in the spec.

# Fuzz and validate an endpoint group against the contract.
pipx run schemathesis run https://ospulse.app/openapi.json \
  --base-url https://api.ospulse.app \
  --header "Authorization: Bearer $OSPULSE_TOKEN" \
  --include-path-regex '^/api/v1/packages' \
  --checks all

Lint the document. If you vendor a copy of the spec, lint it so a corrupted or truncated download fails loudly instead of producing a broken client:

npx @stoplight/spectral-cli lint openapi.json --ruleset spectral:oas

Import into an API client

Every mainstream HTTP client imports OpenAPI directly, which gives you a working request collection in seconds instead of hand-typing URLs.

Import → Link → https://ospulse.app/openapi.json
 
Then create an environment with:
  baseUrl = https://api.ospulse.app
  token   = your API token
 
Set collection Authorization to "Bearer Token" with {{token}} so every
request inherits it, and override the imported server variable with baseUrl.

Keeping generated clients in sync

A generated client is a snapshot. The API keeps moving, so decide deliberately when to catch up rather than finding out at runtime.

curl -s https://ospulse.app/openapi.json | shasum -a 256 | cut -d' ' -f1 > openapi.sha256

live="$(curl -s https://ospulse.app/openapi.json | shasum -a 256 | cut -d' ' -f1)"
pinned="$(cat openapi.sha256)"
 
if [ "$live" != "$pinned" ]; then
  echo "OpenAPI spec changed — regenerate the client and review the diff"
  exit 1
fi

oasdiff breaking openapi.json <(curl -s https://ospulse.app/openapi.json)

Next steps