API Reference

The Spanwise REST API lets you manage checks, environments, and channels programmatically.

Interactive API Docs (Swagger)

Authentication

All API requests require authentication via an API key. Include your key in the Authorization header:

Authorization: Bearer hp_your_api_key

Create API keys in your environment settings. Keys are scoped to a single environment.

Base URL

https://api.spanwise.dev/v1

Endpoints

Ping (Public)

Send pings to your checks. No authentication required.

GET  /ping/:checkId          # Success ping
GET  /ping/:checkId/start    # Job started
GET  /ping/:checkId/fail     # Job failed
POST /ping/:checkId          # Success with body

Checks

GET    /v1/checks                    # List checks in environment
GET    /v1/checks/:id                # Get check details
POST   /v1/checks                    # Create check
PATCH  /v1/checks/:id                # Update check
DELETE /v1/checks/:id                # Delete check
POST   /v1/checks/:id/pause          # Pause check
POST   /v1/checks/:id/resume         # Resume check
GET    /v1/checks/:id/stats          # Uptime stats

Environments

GET    /v1/environments              # List environments
GET    /v1/environments/:id          # Get environment
POST   /v1/environments              # Create environment
PATCH  /v1/environments/:id          # Update environment
DELETE /v1/environments/:id          # Delete environment

Channels

GET    /v1/channels                  # List channels
GET    /v1/channels/:id              # Get channel
POST   /v1/channels                  # Create channel
PATCH  /v1/channels/:id              # Update channel
DELETE /v1/channels/:id              # Delete channel
POST   /v1/channels/:id/test         # Send test notification

Organizations

GET    /v1/organizations             # List organizations
GET    /v1/organizations/:id         # Get organization
POST   /v1/organizations             # Create organization
PATCH  /v1/organizations/:id         # Update organization
DELETE /v1/organizations/:id         # Delete organization

API Keys

GET    /v1/api-keys                  # List API keys
POST   /v1/api-keys                  # Create API key
DELETE /v1/api-keys/:id              # Delete API key

Error Responses

All errors return a JSON object with error and message fields:

{
  "error": "NOT_FOUND",
  "message": "Check not found"
}

Common Error Codes

  • 400 — Bad request (invalid input)
  • 401 — Unauthorized (invalid or missing API key)
  • 403 — Forbidden (no access to resource)
  • 404 — Not found
  • 429 — Rate limited
  • 500 — Server error

Rate Limits

API requests are rate limited to 100 requests per minute per API key.

Ping endpoints (/ping/*) have higher limits: 1000 requests per minute per check.