Components API

Manage components programmatically.

Overview

Components represent services, systems, and infrastructure. The API supports:

CRUD operations
Type-specific configuration
Health check management
Cloning components

Endpoints

Method	Endpoint	Description
GET	`/components`	List all components
POST	`/components`	Create component
GET	`/components/{id}`	Get component
PATCH	`/components/{id}`	Update component
DELETE	`/components/{id}`	Delete component
POST	`/components/{id}/clone`	Clone component
POST	`/components/{id}/check`	Trigger health check

List Components

GET /api/v1/components

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type: SERVICE, ENDPOINT, METRIC
`status`	string	Filter by status
`parentId`	string	Filter by parent component
`topLevelOnly`	boolean	Only top-level components
`includeChecks`	boolean	Include recent health checks
`page`	number	Page number (default: 1)
`pageSize`	number	Items per page (default: 20)

Response

{
  "data": [
    {
      "id": "comp_123",
      "name": "API Server",
      "type": "ENDPOINT",
      "status": "operational",
      "description": "Main API endpoint",
      "url": "https://api.example.com/health",
      "checkInterval": 60,
      "uptimePercentage": 99.95,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-22T10:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "pageSize": 20
  }
}

Create Component

POST /api/v1/components

SERVICE Type

{
  "name": "Backend Services",
  "type": "SERVICE",
  "description": "Core backend infrastructure",
  "status": "operational"
}

ENDPOINT Type

{
  "name": "Health Check",
  "type": "ENDPOINT",
  "description": "API health endpoint",
  "url": "https://api.example.com/health",
  "method": "GET",
  "checkInterval": 60,
  "timeout": 5000,
  "headers": {
    "Authorization": "Bearer token"
  },
  "conditions": [
    {
      "type": "STATUS_CODE",
      "comparator": "EQUALS",
      "target": "200"
    },
    {
      "type": "RESPONSE_TIME",
      "comparator": "LESS_THAN",
      "target": "1000"
    }
  ],
  "autoCreateIncident": true,
  "failureThreshold": 3,
  "parentComponentId": "parent_id"
}

METRIC Type

{
  "name": "CPU Usage",
  "type": "METRIC",
  "description": "Server CPU utilization",
  "integrationId": "integration_id",
  "query": "avg:system.cpu.user{*}",
  "pollingInterval": 60,
  "warningThreshold": 70,
  "criticalThreshold": 90
}

Response

{
  "id": "comp_456",
  "name": "Health Check",
  "type": "ENDPOINT",
  "status": "operational",
  "isEnabled": true,
  "createdAt": "2026-01-22T10:00:00Z"
}

Get Component

GET /api/v1/components/{id}

Query Parameters

Parameter	Type	Description
`include`	string	Comma-separated: subComponents, monitors, checks

Response

{
  "id": "comp_123",
  "name": "API Server",
  "type": "ENDPOINT",
  "status": "operational",
  "description": "Main API endpoint",
  "url": "https://api.example.com/health",
  "method": "GET",
  "checkInterval": 60,
  "timeout": 5000,
  "conditions": [...],
  "uptimePercentage": 99.95,
  "averageResponseTime": 150,
  "lastCheckAt": "2026-01-22T10:00:00Z",
  "subComponents": [...],
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-22T10:00:00Z"
}

Update Component

PATCH /api/v1/components/{id}

Request Body

Only include fields to update:

{
  "name": "Updated Name",
  "status": "degraded_performance",
  "isEnabled": false,
  "isMuted": true
}

Muting

Set isMuted: true to suppress notifications while still monitoring:

{
  "isMuted": true
}

Delete Component

DELETE /api/v1/components/{id}

⚠️

Deleting a component also deletes:

All subcomponents
Historical uptime data
Associated metrics

Response

{
  "success": true
}

Clone Component

POST /api/v1/components/{id}/clone

Creates a copy with:

"(Copy)" suffix on name
isEnabled: false by default
Status reset to operational/unknown

Response

{
  "id": "comp_789",
  "name": "API Server (Copy)",
  "type": "ENDPOINT",
  "isEnabled": false
}

Trigger Health Check

POST /api/v1/components/{id}/check

Manually trigger a health check for ENDPOINT components.

Response

{
  "success": true,
  "result": {
    "status": "SUCCESS",
    "statusCode": 200,
    "responseTime": 145,
    "timestamp": "2026-01-22T10:00:00Z"
  }
}

Component Object

Common Fields

Field	Type	Description
`id`	string	Unique identifier
`name`	string	Display name
`type`	string	SERVICE, ENDPOINT, METRIC
`status`	string	Current status
`description`	string	Optional description
`isEnabled`	boolean	Whether active
`parentComponentId`	string	Parent component ID
`icon`	string	Custom icon URL
`showIconOnStatusPage`	boolean	Show icon publicly
`order`	number	Display order
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp

ENDPOINT Fields

Field	Type	Description
`url`	string	Endpoint URL
`method`	string	HTTP method
`headers`	object	Request headers
`body`	string	Request body
`checkInterval`	number	Check interval (seconds)
`timeout`	number	Request timeout (ms)
`conditions`	array	Health conditions
`autoCreateIncident`	boolean	Create incident on failure
`failureThreshold`	number	Failures before incident
`autoResolve`	boolean	Resolve on recovery
`recoveryThreshold`	number	Successes before resolve
`isMuted`	boolean	Suppress notifications

METRIC Fields

Field	Type	Description
`integrationId`	string	Integration ID
`query`	string	Metrics query
`pollingInterval`	number	Poll interval (seconds)
`warningThreshold`	number	Warning threshold
`criticalThreshold`	number	Critical threshold

Status Values

Status	Description
`operational`	Working normally
`degraded_performance`	Slower than normal
`partial_outage`	Some features unavailable
`major_outage`	Service is down
`under_maintenance`	Planned maintenance

Condition Types

Type	Description
`STATUS_CODE`	HTTP status code
`RESPONSE_TIME`	Response latency
`JSON_PATH`	JSON value assertion
`HEADER`	Response header check
`BODY_CONTAINS`	Body substring check

Comparators

Comparator	Description
`EQUALS`	Exact match
`NOT_EQUALS`	Does not match
`GREATER_THAN`	Above value
`LESS_THAN`	Below value
`CONTAINS`	Contains substring
`EXISTS`	Field exists
`NOT_EXISTS`	Field doesn't exist

Error Responses

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Component not found"
  }
}

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid component type",
    "details": {
      "field": "type",
      "expected": "SERVICE | ENDPOINT | METRIC"
    }
  }
}

Examples

Create Monitored API

curl -X POST https://your-domain.com/api/v1/components \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "type": "ENDPOINT",
    "url": "https://api.example.com/health",
    "method": "GET",
    "checkInterval": 30,
    "conditions": [
      {"type": "STATUS_CODE", "comparator": "EQUALS", "target": "200"}
    ],
    "autoCreateIncident": true,
    "failureThreshold": 3
  }'

Update Status

curl -X PATCH https://your-domain.com/api/v1/components/comp_123 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "degraded_performance"
  }'

Get with Subcomponents

curl "https://your-domain.com/api/v1/components/comp_123?include=subComponents" \
  -H "Authorization: Bearer sk_live_xxx"

Authentication Incidents