API Reference

Complete reference for the a11ops API. Use our SDKs for the best experience, or make direct HTTP requests to our REST API.

Base URL

https://api.a11ops.com

All API requests should be made to this base URL. The API uses standard HTTP response codes and returns JSON for all responses.

Authentication

API Key Authentication

Authenticate requests using your workspace API key in the URL path:

POST /alerts/YOUR_WORKSPACE_API_KEY

Getting Your API Key

  1. Log in to your a11ops dashboard
  2. Navigate to your workspace settings
  3. Find your API key in the “API Keys” section
  4. Keep your API key secure and never commit it to version control

Alert Ingestion

POST/alerts/{workspaceApiKey}

Send an alert to your workspace. This is the primary endpoint for alert ingestion.

Request Body

{
  "title": "string",          // Required - Alert title
  "message": "string",        // Optional - Alert description/body
  "severity": "string",       // Optional - critical | high | medium | low | info
  "priority": "string",       // Optional - Alias for severity
  "timestamp": "string",      // Optional - ISO 8601 timestamp
  "metadata": {              // Optional - Custom key-value pairs
    "key": "value"
  }
}

Examples

// Using the SDK (recommended)
import { a11ops } from '@a11ops/sdk';

await a11ops.alert({
  title: "Database CPU at 95%",
  message: "Primary database server experiencing high load",
  priority: "critical",
  metadata: {
    server: "db-primary-01",
    cpu: 95.3,
    duration: "5 minutes"
  }
});

// Using fetch directly
const response = await fetch('https://api.a11ops.com/alerts/YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: "Database CPU at 95%",
    message: "Primary database server experiencing high load",
    severity: "critical",
    metadata: {
      server: "db-primary-01",
      cpu: 95.3,
      duration: "5 minutes"
    }
  })
});

Response

// Success - 200 OK
{
  "success": true,
  "alertId": "alert_1234567890",
  "timestamp": "2024-01-15T10:30:00Z"
}

// Error - 400 Bad Request
{
  "error": "Invalid severity level",
  "validValues": ["critical", "high", "medium", "low", "info"]
}

// Error - 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Log Monitoring

POST/api/logs/{workspaceApiKey}

Capture and track application logs and errors with full context. Logs are automatically grouped, analyzed, and can trigger alerts based on patterns.

Request Body

{
  "message": "string",        // Required - Error message
  "type": "string",          // Optional - Error type (e.g., "TypeError")
  "level": "string",         // Optional - debug | info | warning | error | fatal | critical
  "stack_trace": "string",   // Optional - Full stack trace
  "platform": "string",      // Optional - browser | node | python | etc.
  "environment": "string",   // Optional - production | staging | development
  "release": "string",       // Optional - Version/release identifier
  "fingerprint": "string",   // Optional - Custom grouping fingerprint
  
  "contexts": {              // Optional - Runtime context
    "os": {},
    "browser": {},
    "device": {}
  },
  
  "user": {                  // Optional - User information
    "id": "string",
    "email": "string",
    "username": "string"
  },
  
  "tags": {                  // Optional - Custom tags
    "key": "value"
  },
  
  "extra": {},               // Optional - Additional data
  "breadcrumbs": [],         // Optional - Event trail
  "request": {}              // Optional - HTTP request data
}

Example Request

// Using the SDK (recommended)
client.logs.captureError(new Error('Payment failed'), {
  level: 'error',
  tags: { module: 'payment' },
  user: { id: '123', email: 'user@example.com' },
  extra: { order_id: 'order_456' }
});

// Direct API call
fetch('https://api.a11ops.com/api/logs/YOUR_API_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: 'Payment failed',
    type: 'PaymentError',
    level: 'error',
    stack_trace: error.stack,
    user: { id: '123', email: 'user@example.com' }
  })
});

Response

// Success - 200 OK
{
  "error_id": 12345,
  "occurrence_id": 67890,
  "grouped": true  // Whether error was grouped with existing
}

// Error - 429 Too Many Requests
{
  "error": "Monthly error quota exceeded",
  "limit": 10000,
  "usage": 10001
}

Log Levels

debugDiagnostic information and debugging logs
infoInformational messages and events
warningWarning conditions that might need attention
errorError conditions in the application
fatalCritical failures requiring immediate attention
criticalSystem-critical issues affecting operations

Severity Levels

Critical

severity: “critical”

System is down or severely impacted. Requires immediate attention.

High / Error

severity: “high”

Significant issues that need prompt attention but system is still operational.

Medium / Warning

severity: “medium”

Warning conditions that should be investigated but are not immediately critical.

Low

severity: “low”

Minor issues or notifications that require attention during normal hours.

Info

severity: “info”

Informational messages for tracking and auditing purposes.

SDK Methods

Simple API (Recommended)

a11ops.alert(options)

Send an alert with custom options

a11ops.critical(title, message?)

Send a critical severity alert

a11ops.error(title, message?)

Send a high severity error alert

a11ops.warning(title, message?)

Send a medium severity warning

a11ops.info(title, message?)

Send an informational alert

Class-based API

new A11ops(apiKey, options?)

Create a new client instance

client.alert(options)

Send an alert

client.batchAlert(alerts[])

Send multiple alerts in one request

client.getMetrics(options)

Retrieve delivery metrics

client.getSLACompliance(options)

Get SLA compliance data

Configuration Options

Client Options

interface ClientOptions {
  baseUrl?: string;      // API endpoint (default: https://api.a11ops.com)
  region?: string;       // Target region: auto | us-west-2 | us-east-1
  timeout?: number;      // Request timeout in ms (default: 30000)
  retries?: number;      // Number of retry attempts (default: 3)
  retryDelay?: number;   // Delay between retries in ms (default: 1000)
}

Rate Limiting

API requests are rate-limited per workspace to ensure fair usage:

  • Alert ingestion: Based on your subscription plan
  • Authentication endpoints: 10 requests per minute per IP
  • Rate limit headers are included in all responses
// Rate limit headers
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1673876543

Error Handling

HTTP Status Codes

200 OKRequest succeeded
400 Bad RequestInvalid request data
401 UnauthorizedInvalid or missing API key
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error, request should be retried

SDK Error Handling

try {
  await a11ops.alert({ title: "Test alert" });
} catch (error) {
  if (error.status === 429) {
    // Rate limited - wait and retry
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error.code === 'ENORESPONSE') {
    // Network error
    console.error('Network connectivity issue');
  } else {
    // API error
    console.error(`API Error: ${error.message}`);
  }
}

Webhook Receivers

a11ops can receive alerts from external monitoring tools via webhooks. Configure your monitoring tool to send webhooks to:

POST https://api.a11ops.com/v1/webhooks/{integrationId}

The webhook payload will be automatically transformed into a11ops alerts. We support native formats from:

  • Prometheus AlertManager
  • Grafana
  • Datadog
  • Generic JSON webhooks

Additional Resources

Explore our SDKs, integration guides, and example applications.

View SDK on GitHubIntegration Guides