Skip to main content

API Reference

Automate your monitoring configuration with the BlackTide REST API. Full programmatic access to all features.

Authentication

All API requests must include an API token in the Authorization header using the Bearer authentication scheme.

Example Request with Authentication
bash
curl -X GET "https://api.blacktide.xyz/v1/monitors" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

You can generate API tokens in your Account Settings under the "API" tab. Each token is scoped to your team and inherits your user permissions.

Base URL

text
https://api.blacktide.xyz/v1

Response Format

All API responses return JSON with the following structure:

Success Response
json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production API"
  }
}
Error Response
json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid monitor configuration",
    "details": {
      "url": "URL is required"
    }
  }
}

Endpoints Overview

Monitors

MethodEndpointDescription
GET/monitorsList all monitors
POST/monitorsCreate a new monitor
GET/monitors/:idGet monitor details
PATCH/monitors/:idUpdate a monitor
DELETE/monitors/:idDelete a monitor
POST/monitors/:id/testTest monitor connection

Create Monitor Example

Create HTTP Monitor
bash
curl -X POST "https://api.blacktide.xyz/v1/monitors" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "http",
    "url": "https://api.example.com/health",
    "interval": 60,
    "timeout": 30,
    "locations": ["us-east-1", "eu-west-1"]
  }'

Incidents

MethodEndpointDescription
GET/incidentsList all incidents
POST/incidentsCreate manual incident
GET/incidents/:idGet incident details
PATCH/incidents/:idUpdate incident status

Alert Rules & Channels

MethodEndpointDescription
GET/alert-rulesList alert rules
POST/alert-rulesCreate alert rule
GET/alert-channelsList alert channels
POST/alert-channelsCreate alert channel

Status Pages

MethodEndpointDescription
GET/status-pagesList status pages
POST/status-pagesCreate status page
PATCH/status-pages/:idUpdate status page

Pagination

List endpoints support cursor-based pagination:

Paginated Request
bash
curl "https://api.blacktide.xyz/v1/monitors?limit=50&cursor=abc123"
Paginated Response
json
{
  "success": true,
  "data": [...],
  "pagination": {
    "nextCursor": "xyz789",
    "hasMore": true
  }
}

Rate Limits

API usage is rate-limited based on your plan to ensure fair usage and system stability:

PlanRequests/HourBurst Limit
Free10010/min
Developer50050/min
Pro1,000100/min
EnterpriseUnlimitedUnlimited

Rate Limit Headers

Every API response includes rate limit information:

text
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1699555200

Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request payload
UNAUTHORIZED401Invalid or missing API token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Server error

Webhooks

Subscribe to real-time events via webhooks. See the Webhooks Integration Guide for detailed setup instructions.

SDKs & Libraries

Further Reading

Related Articles