API And Webhooks

The Bitaic API and webhook layer lets engineering, operations, and automation teams retrieve monitoring data, manage monitored resources, configure alert behavior, export operational data, and deliver operational events into internal systems.

When To Use API Versus Webhooks

Need	Use	Typical workflow
Read current or historical state on demand.	API	Query targets, checks, metrics, alerts, or exports from a script, dashboard, or internal tool.
Create or update monitoring configuration from automation.	API	Manage monitored targets, check schedules, alert thresholds, integration settings, and agent metadata.
React when something changes.	Webhooks	Send alert, recovery, certificate, endpoint, DNS, or domain events to another system.
Connect Bitaic to incident or workflow tools.	Integrations and webhooks	Use a built-in integration where one exists, and use webhooks for custom routing or in-house automation.

Authentication And Authorization

• API requests use a Bitaic API token in the Authorization: Bearer <token> header.
• API tokens are workspace-scoped service tokens created and rotated from Bitaic App settings by users with permission to manage API access.
• Requests are authorized against the workspace in the URL path and the scopes granted to the token.
• Administrative API activity is part of the Bitaic audit trail so teams can review configuration and access changes.

Base URL And Versioning

Resource Model

Target And Check Types

Endpoint Reference

Create A Monitored Target

Use targets for monitored objects and attach one or more checks to decide what Bitaic should evaluate.

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/targets HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: target-create-20260825-001

{
  "type": "endpoint",
  "name": "Production API",
  "labels": {
    "service": "checkout",
    "environment": "production"
  },
  "config": {
    "url": "https://api.example.com/health",
    "method": "GET",
    "follow_redirects": true,
    "max_redirects": 5,
    "expected_status_codes": ["200-399"],
    "timeout_ms": 10000
  }
}

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/targets HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: target-create-20260826-002

{
  "type": "dns_record",
  "name": "Production API DNS",
  "labels": {
    "service": "checkout",
    "environment": "production"
  },
  "config": {
    "record_name": "www.example.com",
    "record_type": "A"
  }
}

{
  "data": {
    "id": "target_01J5Z8M4Q9K7P6N2H1W8R5T3A1",
    "workspace_id": "workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X",
    "type": "endpoint",
    "name": "Production API",
    "status": "healthy",
    "labels": {
      "service": "checkout",
      "environment": "production"
    },
    "created_at": "2026-08-25T14:30:00Z",
    "updated_at": "2026-08-25T14:30:00Z"
  },
  "request_id": "req_01J5Z8T6N9QVH6CY7W0Z6QG1F2"
}

Create A Check

Checks hold schedules, thresholds, and product-specific rule configuration. The same endpoint target can have both endpoint_availability and ssl_certificate checks.

Endpoint response-time thresholds use thresholds.response_time_ms.warning and thresholds.response_time_ms.critical in whole milliseconds. If omitted, Bitaic uses 1000 ms for warning and 3000 ms for critical; custom values must be supplied together, must be positive integers, and critical must be greater than warning and no higher than the check timeout.

Domain Monitoring uses expiration_alert_days as its numeric threshold. It defaults to 30 calendar days and accepts integers from 1 through 365. Nameserver, DNSSEC, and registrar-lock alerts are expected-state checks: they alert only when the relevant expected value is configured.

DNS Monitoring uses dns_resolution checks with launch record types A, AAAA, CNAME, MX, TXT, NS, and CAA records. Default checks run every 60 seconds from us-east, us-west, and eu-west resolver regions, use a 2-second resolver-query timeout, and use max_latency_ms with a 500 ms default. Optional controls include authoritative_check, expected_ttl_seconds, dnssec_validation, and propagation_grace_period_minutes.

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/targets/target_01J5Z8M4Q9K7P6N2H1W8R5T3A1/checks HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: check-create-20260825-001

{
  "type": "endpoint_availability",
  "enabled": true,
  "schedule": {
    "interval_seconds": 60
  },
  "thresholds": {
    "response_time_ms": {
      "warning": 1000,
      "critical": 3000
    }
  }
}

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/targets/target_01J5Z9D7M4P2Q8R6T1V3W5X7Y/checks HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: check-create-20260826-002

{
  "type": "domain_status",
  "enabled": true,
  "schedule": {
    "interval_hours": 24
  },
  "expiration_alert_days": 30,
  "expected_nameservers": [
    "ns1.example-dns.com",
    "ns2.example-dns.com"
  ],
  "expected_dnssec_state": "enabled",
  "expected_registrar_lock_state": "locked"
}

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/targets/target_01J5ZA9K8W7Q6R5T4Y3U2I1O0/checks HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: check-create-20260826-003

{
  "type": "dns_resolution",
  "enabled": true,
  "schedule": {
    "interval_seconds": 60
  },
  "resolver_regions": [
    "us-east",
    "us-west",
    "eu-west"
  ],
  "expected_values": [
    "203.0.113.10"
  ],
  "alert_on_mismatch": true,
  "max_latency_ms": 500,
  "timeout_ms": 2000,
  "authoritative_check": true,
  "expected_ttl_seconds": {
    "min": 60,
    "max": 3600
  },
  "dnssec_validation": "observe",
  "propagation_grace_period_minutes": 30
}

Retrieve Metrics

Metrics are queried by target, check, metric name, and a bounded time window. Use rollup and interval for charts, reports, and exports that do not need raw samples.

Domain Monitoring emits domain.days_until_expiration when expiration data is available. Domain check records also expose registrar, registry status, nameserver state, DNSSEC state, registrar-lock state, RDAP/WHOIS retrieval state, and checked timestamp.

GET /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/metrics?target_id=target_01J5Z8M4Q9K7P6N2H1W8R5T3A1&metric=endpoint.response_time_ms&from=2026-08-25T13:30:00Z&to=2026-08-25T14:30:00Z&rollup=avg&interval=5m HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Accept: application/json

{
  "data": [
    {
      "target_id": "target_01J5Z8M4Q9K7P6N2H1W8R5T3A1",
      "check_id": "check_01J5ZA8FJ2N7G5Q0HF4P12V7XD",
      "metric": "endpoint.response_time_ms",
      "unit": "ms",
      "value": 248,
      "observed_at": "2026-08-25T14:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  },
  "request_id": "req_01J5Z8T6N9QVH6CY7W0Z6QG1F2"
}

Pagination, Filtering, And Limits

• List APIs support cursor pagination with limit and cursor. The default limit is 50, and the maximum limit is 100.
• Cursor responses include pagination.next_cursor and pagination.has_more.
• Metric and delivery queries require bounded from and to timestamps.
• Rate-limit responses include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After on 429.

Permissions And Token Scopes

Use separate tokens for read-only reporting, configuration automation, alert operations, and integration management. A token can act only inside the workspace and scopes assigned to it.

Manage Integrations

Use integration resources for built-in provider destinations such as Slack, Microsoft Teams, email, and PagerDuty preview routing. Custom event receivers use webhook subscriptions.

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/integrations HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: integration-create-20260825-001

{
  "provider": "slack",
  "name": "Production operations alerts",
  "enabled": true,
  "filters": {
    "severity": ["warning", "critical"],
    "product": ["endpoint", "ssl"],
    "label": {
      "environment": "production"
    },
    "state": ["open", "resolved"]
  },
  "config": {
    "channel_id": "C0123456789",
    "include_recoveries": true
  }
}

{
  "data": {
    "id": "int_01J5ZAG2FF4V18T8G3J8K4N6XQ",
    "workspace_id": "workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X",
    "provider": "slack",
    "name": "Production operations alerts",
    "enabled": true,
    "status": "active",
    "filters": {
      "severity": ["warning", "critical"],
      "product": ["endpoint", "ssl"],
      "label": {
        "environment": "production"
      },
      "state": ["open", "resolved"]
    },
    "created_at": "2026-08-25T14:30:00Z",
    "updated_at": "2026-08-25T14:30:00Z"
  },
  "request_id": "req_01J5ZAHX5TWW2E1V8W9S3CVR42"
}

• Integration filters support severity, product, target_id, check_id, label, team, service, and state where the provider and selected event include that field.
• PagerDuty preview uses Events API v2 routing keys and the Bitaic alert ID as the PagerDuty dedup_key.
• API keys are created from Bitaic App settings and controlled by token scopes rather than integration routing filters.

Errors And Recovery

{
  "error": {
    "code": "validation_failed",
    "message": "One or more request fields are invalid.",
    "field": "config.expected_status_codes",
    "details": [
      {
        "field": "config.expected_status_codes",
        "message": "At least one expected status code is required."
      }
    ]
  },
  "request_id": "req_01J5Z8W6YF5QA20NHJ9FE7J7VQ"
}

Manage Webhook Subscriptions

Webhook subscriptions define where Bitaic sends events, which event names are selected, which filters apply, and whether delivery is currently enabled.

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/webhook-subscriptions HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: webhook-subscription-20260825-001

{
  "url": "https://automation.example.com/bitaic/webhooks",
  "description": "Production operations receiver",
  "events": [
    "alert.created",
    "alert.resolved",
    "endpoint.check_failed",
    "ssl.expiring",
    "agent.offline"
  ],
  "filters": {
    "severity": ["warning", "critical"],
    "product": ["endpoint", "ssl"],
    "label": {
      "environment": "production"
    }
  },
  "enabled": true
}

{
  "data": {
    "id": "whsub_01J5Z8ZYK2M4X7P2Q9BH8E3E2R",
    "workspace_id": "workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X",
    "url": "https://automation.example.com/bitaic/webhooks",
    "description": "Production operations receiver",
    "events": [
      "alert.created",
      "alert.resolved",
      "endpoint.check_failed",
      "ssl.expiring",
      "agent.offline"
    ],
    "filters": {
      "severity": ["warning", "critical"],
      "product": ["endpoint", "ssl"],
      "label": {
        "environment": "production"
      }
    },
    "enabled": true,
    "status": "active",
    "signing_secret": "whsec_01J5Z92Y3EJ9G5X8S5PS7VN2BB",
    "secret_last_rotated_at": "2026-08-25T14:30:00Z",
    "created_at": "2026-08-25T14:30:00Z",
    "updated_at": "2026-08-25T14:30:00Z"
  },
  "request_id": "req_01J5Z930ZPK7VYV3XG3C7Z9WNQ"
}

• Bitaic returns signing_secret only when a subscription is created or rotated.
• Rotate a secret with /v1/workspaces/{workspace_id}/webhook-subscriptions/{subscription_id}/secret/rotate.
• During rotation, Bitaic includes signatures for the current and previous secret for 24 hours so receivers can deploy the new secret without dropping events.

Webhook Events

Webhook Payload And Security

Webhook deliveries use HTTPS, include a unique event ID, and provide the event name, delivery timestamp, workspace context, and related resource payload. Receivers should verify the signature before processing the event.

POST /bitaic/webhooks HTTP/1.1
Host: automation.example.com
Content-Type: application/json
X-Bitaic-Event: alert.created
X-Bitaic-Delivery: whd_01J5Z91CBA9W37F68JTE7W8JEV
X-Bitaic-Timestamp: 2026-08-25T14:30:00Z
X-Bitaic-Signature: v1=<hex_hmac_sha256>

{
  "event_id": "evt_01J5Z91CBA9W37F68JTE7W8JEV",
  "event_type": "alert.created",
  "api_version": "v1",
  "created_at": "2026-08-25T14:30:00Z",
  "workspace_id": "workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X",
  "subscription_id": "whsub_01J5Z8ZYK2M4X7P2Q9BH8E3E2R",
  "delivery_id": "whd_01J5Z91CBA9W37F68JTE7W8JEV",
  "attempt": 1,
  "data": {
    "alert": {
      "id": "alert_01J5Z8P2A9W8H2XP0J4K3V7B8C",
      "severity": "critical",
      "state": "open",
      "summary": "Endpoint response time exceeded threshold",
      "target_id": "target_01J5Z8M4Q9K7P6N2H1W8R5T3A1",
      "check_id": "check_01J5ZA8FJ2N7G5Q0HF4P12V7XD"
    },
    "target": {
      "id": "target_01J5Z8M4Q9K7P6N2H1W8R5T3A1",
      "type": "endpoint",
      "name": "Production API"
    }
  }
}

• Build the signed value from X-Bitaic-Timestamp + "." + X-Bitaic-Delivery + "." + raw_request_body.
• Validate X-Bitaic-Signature by calculating an HMAC-SHA256 digest with the webhook signing secret and comparing the v1 value in constant time.
• Verify the raw request body before JSON parsing, and reject timestamps older than five minutes.
• Treat event_id and X-Bitaic-Delivery as idempotency values to prevent duplicate processing.
• Respond with a 2xx status after successful processing.
• During secret rotation, accept any valid v1 signature generated by either the current or previous signing secret.

Delivery Guarantees And Retries

Webhooks are delivered at least once. Consumers should handle duplicate deliveries and should not depend on global ordering across subscriptions, products, or targets.

Bitaic retains webhook delivery attempt records for 30 days. Test deliveries use the same timeout and signature behavior as production deliveries, but they do not count toward system-disable thresholds.

Webhook Delivery Records

Use delivery records to troubleshoot receiver failures, identify retry timing, and correlate downstream automation with Bitaic event IDs.

GET /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/webhook-deliveries?subscription_id=whsub_01J5Z8ZYK2M4X7P2Q9BH8E3E2R&status=retrying&from=2026-08-25T00:00:00Z&to=2026-08-25T23:59:59Z HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Accept: application/json

{
  "data": [
    {
      "id": "whd_01J5Z91CBA9W37F68JTE7W8JEV",
      "event_id": "evt_01J5Z91CBA9W37F68JTE7W8JEV",
      "event_type": "alert.created",
      "subscription_id": "whsub_01J5Z8ZYK2M4X7P2Q9BH8E3E2R",
      "status": "retrying",
      "attempt": 2,
      "response_status": 503,
      "next_attempt_at": "2026-08-25T14:36:00Z",
      "created_at": "2026-08-25T14:30:00Z",
      "updated_at": "2026-08-25T14:31:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  },
  "request_id": "req_01J5Z9KJCPZ85FRJN2X7B2S4MD"
}

Data Export

API exports support operational reporting, compliance review, backup, and downstream analytics. Export requests should include the resource area, target scope, time window, and desired output format.

POST /v1/workspaces/workspace_01J5Z82DB7YV6PRPK6K4WSGJ5X/exports HTTP/1.1
Host: api.bitaic.com
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: export-20260825-001

{
  "resource": "alerts",
  "format": "csv",
  "from": "2026-08-01T00:00:00Z",
  "to": "2026-08-25T23:59:59Z",
  "filters": {
    "state": "resolved",
    "severity": ["warning", "critical"]
  }
}

Security Notes

• Use least-privilege tokens for automation and rotate them on a regular schedule.
• Separate read-only reporting tokens from tokens that can create, update, or delete configuration.
• Restrict webhook receivers to HTTPS endpoints controlled by your organization.
• Log request_id, event_id, and delivery IDs in downstream systems for support and audit review.
• Avoid forwarding secrets, credentials, or unnecessary sensitive details through webhook payloads or exports.

Related Workflows

• Integrations for Slack, Microsoft Teams, email, PagerDuty, and custom webhook routing.
• Certificate Monitoring for certificate status, expiration thresholds, and HTTPS certificate diagnostics.
• Endpoint Monitoring for endpoint availability, response time, and uptime states.
• DNS Monitoring for resolver checks, DNS latency, and record mismatches.
• Domain Monitoring for expiration, registry metadata, nameserver, DNSSEC, and registrar-lock signals.
• Audit for reviewing administrative and security-relevant activity.