Quickstart
Go from nothing to a verified 200 OK from the OSPulse API in about five minutes.
Before you start
You need an OSPulse account at app.ospulse.app. Everything
below runs against the production API at https://api.ospulse.app.
Check the API is reachable
The health endpoint needs no authentication, which makes it the fastest way to confirm you can reach the API and that your network allows it.
curl https://api.ospulse.app/api/v1/healthYou should get back a payload reporting overall health and each checked dependency:
{
"status": "Healthy",
"totalDuration": "00:00:00.0025332",
"entries": {
"postgres": {
"status": "Healthy",
"tags": ["db", "ready"]
}
}
}If that returns Healthy, you are ready to authenticate.
Get your first successful call
Create an API token
Sign in to app.ospulse.app and open API tokens in the main navigation — or go straight to app.ospulse.app/api-tokens — then create a token. Copy it immediately: the token value is shown once and is not recoverable afterwards.
The screen is visible to administrators only. If it is not in your navigation, ask an administrator in your tenant to issue a token for you.
You can also create one through the API itself if you already hold a token:
curl -X POST https://api.ospulse.app/api/v1/api-tokens \
-H "Authorization: Bearer $OSPULSE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "local-dev" }'Store it as an environment variable
Never hard-code a token into source. Export it into your shell so the examples below work verbatim:
export OSPULSE_TOKEN="your_token_here"Make an authenticated request
Every authenticated endpoint takes the token as a bearer credential in the
Authorization header. List the packages OSPulse is tracking for your tenant:
curl https://api.ospulse.app/api/v1/packages?take=5 \
-H "Authorization: Bearer $OSPULSE_TOKEN"Read the response
Collection endpoints return a page envelope — the items themselves plus the counters you need to page through the rest:
{
"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
}That is a successful authenticated call. Keep the packageId — most of the package
endpoints, such as health and vulnerabilities, are keyed on it.
totalReturned is not a total count
This endpoint reports totalReturned — how many items came back in this page, not how
many exist overall. Page until a response returns fewer items than you asked for rather
than computing a page count. See pagination.
Keep tokens out of version control
An API token carries the permissions of whoever created it. Store tokens in your secret manager or CI secret store, never in a committed file. If one leaks, revoke it immediately — see Authentication.
Handling errors
Errors use RFC 7807 problem details. A missing or invalid token
returns 401:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Unauthorized",
"status": 401,
"detail": "The supplied API token is missing, expired, or revoked.",
"correlationId": "0HN7GKQ2M3P4A:00000001"
}Always log the correlationId — quoting it lets support trace your exact request.