API Reference

Complete reference for PulseAPI REST endpoints. All requests require authentication.

Authentication

Two methods: JWT tokens (web UI) or API keys (programmatic access).

JWT Token (Web UI)

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

// Response:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": "123", "email": "user@example.com" }
}

API Key (Programmatic)

curl -H "X-API-Key: pk_live_abc123xyz..." \
  https://api.getpulseapi.belliel.com/endpoints

Generate API keys in Dashboard → Settings → API Key

Base URL

https://api.getpulseapi.belliel.com

All endpoints are relative to this base URL.

Endpoints

POST/auth/signup

Create a new user account.

{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "John Doe"
}

Response: 201 Created + JWT token

POST/auth/login

Authenticate and receive JWT token.

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response: 200 OK + JWT token (7-day expiration)

GET/auth/me

Get current user info (requires auth).

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.getpulseapi.belliel.com/auth/me

Response: { "id": "123", "email": "user@example.com", "apiKey": "pk_live_..." }

GET/endpoints

List all endpoints for the authenticated user.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.getpulseapi.belliel.com/endpoints

Response: 200 OK + array of endpoint objects

POST/endpoints

Create a new endpoint to monitor.

{
  "name": "Production API",
  "url": "https://api.example.com/health",
  "method": "GET",
  "checkInterval": 300,  // seconds (5 min)
  "timeout": 10          // seconds
}

Response: 201 Created + endpoint object

Validation:

URL must be valid http/https
Method: GET, POST, PUT, PATCH, DELETE, HEAD
checkInterval: 60-3600 seconds
timeout: 5-60 seconds

GET/endpoints/:id

Get a single endpoint by ID (ownership check).

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.getpulseapi.belliel.com/endpoints/abc123

Response: 200 OK + endpoint object (or 404 if not found/unauthorized)

PATCH/endpoints/:id

Update an existing endpoint (partial update).

{
  "checkInterval": 600  // update to 10 minutes
}

Response: 200 OK + updated endpoint object

DELETE/endpoints/:id

Delete an endpoint (cascade deletes checks + alerts).

curl -X DELETE -H "X-API-Key: YOUR_API_KEY" \
  https://api.getpulseapi.belliel.com/endpoints/abc123

Response: 204 No Content (success)

GET/endpoints/:id/checks

Get check history for an endpoint (paginated).

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.getpulseapi.belliel.com/endpoints/abc123/checks?limit=20&offset=0"

Query Params:

limit: 1-100 (default 20)
offset: pagination offset (default 0)
from: ISO timestamp (filter start)
to: ISO timestamp (filter end)

Response: 200 OK + array of check objects

GET/endpoints/:id/stats

Get aggregated stats (uptime %, avg response time).

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.getpulseapi.belliel.com/endpoints/abc123/stats?period=24h"

Query Params:

period: 24h | 7d | 30d (default 24h)

Response:

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

Error Codes

Code	Description
400	Bad Request (validation error)
401	Unauthorized (missing/invalid auth)
404	Not Found (resource doesn't exist or unauthorized)
409	Conflict (duplicate email)
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Rate Limits

All API requests are rate-limited to prevent abuse.

Plan	Limit
Free	100 requests/hour
Basic ($19/mo)	1,000 requests/hour
Pro ($39/mo)	10,000 requests/hour

Rate limit headers returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Full Example

# 1. Sign up
curl -X POST https://api.getpulseapi.belliel.com/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secure123","name":"John"}'

# 2. Get API key (from response or dashboard)
API_KEY="pk_live_abc123..."

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

# 4. List endpoints
curl -H "X-API-Key: $API_KEY" \
  https://api.getpulseapi.belliel.com/endpoints

# 5. Get stats
curl -H "X-API-Key: $API_KEY" \
  "https://api.getpulseapi.belliel.com/endpoints/abc123/stats?period=24h"

# 6. Get check history
curl -H "X-API-Key: $API_KEY" \
  "https://api.getpulseapi.belliel.com/endpoints/abc123/checks?limit=10"