API Reference

Complete reference for PulseAPI REST endpoints. All requests require authentication unless marked public.

On this page

Authentication

Two authentication methods are supported. Use JWT tokens for web sessions, API keys for scripts and integrations.

API Key (recommended for integrations)

curl -H "Authorization: pk_live_abc123..." \
  https://api.pulseapi.tech/endpoints

Generate API keys in Dashboard → Settings → API Keys. Pass the raw key in the Authorization header (no "Bearer" prefix). Keys are scoped with granular permissions and optional expiry.

JWT Token (web sessions)

# Login to get a token
curl -X POST https://api.pulseapi.tech/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"securepassword"}'

# Use the token
curl -H "Authorization: Bearer eyJhbG..." \
  https://api.pulseapi.tech/endpoints

JWT tokens expire after 7 days. If 2FA is enabled, the login response will include requiresTwoFactor: true and you must provide a TOTP code.

Base URL

https://api.pulseapi.tech

All endpoints below are relative to this base URL. Responses are JSON with Content-Type: application/json.

Interactive API Explorer

Try the API directly in your browser

OpenAPI / Swagger UI with all endpoints, schemas, and live request testing.

Open API Docs →

Endpoints

GET/endpoints

List all monitored endpoints for your organization.

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.pulseapi.tech/endpoints?limit=50&offset=0"

Query params:

limit -- max results (default 50, max 200)
offset -- pagination offset

POST/endpoints

Create a new endpoint to monitor.

{
  "name": "Production API",
  "url": "https://api.example.com/health",
  "method": "GET",
  "checkInterval": 300,
  "timeout": 10,
  "tags": ["production", "critical"]
}

Validation:

URL: valid http/https, SSRF-protected
Method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
checkInterval: 60--3600 seconds (plan minimum may apply)
timeout: 5--60 seconds

GET/endpoints/:id

Get a single endpoint by ID.

curl -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/endpoints/abc123

PATCH/endpoints/:id

Update an existing endpoint (partial update).

{
  "checkInterval": 600,
  "enabled": true,
  "tags": ["staging"]
}

DELETE/endpoints/:id

Delete an endpoint. Cascade-deletes all checks and alerts.

curl -X DELETE -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/endpoints/abc123

POST/endpoints/:id/check

Trigger an immediate check. Runs the full pipeline (status evaluation, alerts).

curl -X POST -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/endpoints/abc123/check

Response

{
  "result": {
    "success": true,
    "statusCode": 200,
    "responseTime": 142
  }
}

POST/endpoints/:id/maintenance

Toggle maintenance mode. Auto-resolves open alerts when enabled.

{
  "enabled": true,
  "until": "2026-04-02T06:00:00Z"
}

Stats & Checks

GET/endpoints/:id/checks

Get check history for an endpoint (paginated, time-filtered).

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.pulseapi.tech/endpoints/abc123/checks?limit=20&from=2026-01-01T00:00:00Z"

Query params:

limit -- number (default 50)
from -- ISO timestamp (start filter)
to -- ISO timestamp (end filter)

GET/endpoints/:id/stats

Get aggregated uptime and performance stats.

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.pulseapi.tech/endpoints/abc123/stats?period=24h"

Response

{
  "uptime": 99.5,
  "avgResponseTime": 250,
  "totalChecks": 288,
  "failedChecks": 1
}

Supported periods: 24h, 7d. Stats for 30d and 90d are available via the summary endpoint.

Incidents

Incidents are scoped to organizations and linked to status pages. All incident routes require the orgId path parameter.

GET/orgs/:orgId/incidents

List incidents for an organization. Filter by status or component.

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.pulseapi.tech/orgs/ORG_ID/incidents?status=investigating&limit=20"

Query params:

status -- investigating, identified, monitoring, resolved
component -- filter by component key
limit, offset -- pagination

POST/orgs/:orgId/incidents

Create a new incident. Notifies status page subscribers and triggers escalation.

{
  "statusPageId": "STATUS_PAGE_ID",
  "title": "Database connectivity issues",
  "status": "investigating",
  "severity": "major",
  "message": "We are investigating reports of increased error rates.",
  "componentKeys": ["database"]
}

Severity options:

criticalmajorminormaintenance

PATCH/orgs/:orgId/incidents/:id

Update incident status, severity, or affected components.

{
  "status": "resolved",
  "severity": "minor"
}

Setting status to resolved automatically sets resolvedAt and cancels pending escalations.

POST/orgs/:orgId/incidents/:id/updates

Add a timeline update to an incident.

{
  "status": "identified",
  "message": "Root cause identified: misconfigured connection pool."
}

DELETE/orgs/:orgId/incidents/:id

Delete an incident and all its updates.

curl -X DELETE -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/orgs/ORG_ID/incidents/INCIDENT_ID

Alerts

GET/alerts

List alerts for your organization's endpoints. Supports filtering and pagination.

curl -H "Authorization: YOUR_API_KEY" \
  "https://api.pulseapi.tech/alerts?resolved=false&limit=20"

Response

{
  "alerts": [
    {
      "id": "uuid",
      "type": "downtime",
      "message": "Endpoint is down: connection refused",
      "resolved": false,
      "createdAt": "2026-01-15T10:30:00Z",
      "endpointId": "uuid",
      "endpointName": "Production API",
      "endpointUrl": "https://api.example.com/health"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Alert types:

downtime -- 2+ consecutive check failures
recovery -- endpoint back online after downtime
slow_response -- response time exceeds threshold (rate-limited: 1/hour)

PATCH/alerts/:id/resolve

Manually resolve an alert with an optional note.

curl -X PATCH -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Fixed by scaling up replicas"}' \
  https://api.pulseapi.tech/alerts/ALERT_ID/resolve

Status Pages

GET/status/:slugpublic

Public endpoint (no auth). Returns the current status of all endpoints on a status page.

curl https://api.pulseapi.tech/status/mycompany

Response

{
  "overallStatus": "operational",
  "updatedAt": "2026-01-15T10:30:00Z",
  "endpoints": [
    {
      "id": "uuid",
      "name": "Production API",
      "status": "up",
      "uptime24h": 99.9,
      "responseTime": 120,
      "lastChecked": "2026-01-15T10:29:00Z"
    }
  ],
  "incidents": [],
  "statusPage": {
    "name": "My Company Status",
    "slug": "mycompany"
  }
}

Also supports custom domain lookup. Set your slug and domain in Dashboard → Status Page.

API Keys

Manage scoped API keys for programmatic access. Keys use a pk_live_ prefix and support granular permission scopes.

POST/orgs/:orgId/api-keys

Create a new API key. The raw key is returned only once.

{
  "name": "CI/CD Pipeline",
  "scopes": ["endpoints:read", "endpoints:write", "alerts:read"],
  "expiresAt": "2027-01-01T00:00:00Z"
}

Available scopes:

endpoints:readendpoints:writeincidents:readincidents:writestatus:readcomponents:readalerts:readalerts:writeorg:readorg:manage

GET/orgs/:orgId/api-keys

List all API keys (shows prefix only, not the full key).

curl -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/orgs/ORG_ID/api-keys

DELETE/orgs/:orgId/api-keys/:keyId

Revoke an API key. Takes effect immediately.

curl -X DELETE -H "Authorization: YOUR_API_KEY" \
  https://api.pulseapi.tech/orgs/ORG_ID/api-keys/KEY_ID

Error Codes

All errors return a JSON body with an error field.

Error response format

{
  "error": "Endpoint not found"
}

Code	Description
400	Bad Request -- validation error or missing fields
401	Unauthorized -- missing or invalid authentication
402	Payment Required -- active subscription needed
403	Forbidden -- insufficient permissions or plan limit reached
404	Not Found -- resource does not exist or not authorized
409	Conflict -- duplicate email, slug, or resource
429	Too Many Requests -- rate limit exceeded
500	Internal Server Error

Rate Limits

Endpoint	Limit	Window
/auth/login	5 requests	15 minutes per IP
/auth/signup	5 requests	15 minutes per IP
Manual checks (trial)	20 tests	24 hours per org

Rate limit headers are returned on applicable endpoints: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

OpenAPI & SDK Generation

PulseAPI exposes an OpenAPI 3.1 specification. Use it to auto-generate a type-safe client in any language.

Fetch the OpenAPI spec

curl -o openapi.json https://api.pulseapi.tech/docs/json

TypeScript (openapi-typescript + openapi-fetch)

bun add -D openapi-typescript openapi-fetch
bunx openapi-typescript openapi.json -o ./pulseapi.d.ts

# Usage:
import createClient from 'openapi-fetch';
import type { paths } from './pulseapi';

const client = createClient({
  baseUrl: 'https://api.pulseapi.tech',
  headers: { Authorization: 'pk_live_abc123...' },
});

const { data } = await client.GET('/endpoints');

Python / Go / Ruby / Java

# Python
pip install openapi-python-client
openapi-python-client generate --url https://api.pulseapi.tech/docs/json

# Any language via OpenAPI Generator (50+ targets)
npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli generate -i openapi.json -g go -o ./pulseapi-go

Full Example

# 1. Create an API key in Dashboard > Settings > API Keys
API_KEY="pk_live_abc123..."

# 2. Create an endpoint
curl -X POST https://api.pulseapi.tech/endpoints \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.example.com/health",
    "method": "GET",
    "checkInterval": 300,
    "timeout": 10
  }'

# 3. List your endpoints
curl -H "Authorization: $API_KEY" \
  https://api.pulseapi.tech/endpoints

# 4. Trigger a manual check
curl -X POST -H "Authorization: $API_KEY" \
  https://api.pulseapi.tech/endpoints/ENDPOINT_ID/check

# 5. Get uptime stats
curl -H "Authorization: $API_KEY" \
  "https://api.pulseapi.tech/endpoints/ENDPOINT_ID/stats?period=24h"

# 6. List active alerts
curl -H "Authorization: $API_KEY" \
  "https://api.pulseapi.tech/alerts?resolved=false"

# 7. Get public status (no auth needed)
curl https://api.pulseapi.tech/status/your-slug