API Reference

Build powerful integrations with com.bond

Getting Started

The com.bond API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

https://com.bond/api/v1

Authentication

Authenticate your API requests by including your secret API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY
Important: Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, etc.

Rate Limits

API rate limits vary by plan:

Plan Requests/minute Requests/hour Burst limit
Startup 60 1,000 10
Business 300 10,000 50
Enterprise Custom Custom Custom

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Request limit per hour
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Domains

POST /domains/verify

Initiate domain verification process

Request Body

Parameter Type Description
domain * string The .com domain to verify (e.g., "example.com")
method string Verification method: "dns" (default), "html", "meta"

Response

{ "id": "ver_1234567890", "domain": "example.com", "method": "dns", "status": "pending", "verification_record": { "type": "TXT", "host": "_com-bond-verify", "value": "combond-verify-abc123def456", "ttl": 300 }, "created_at": "2025-01-10T12:00:00Z", "expires_at": "2025-01-17T12:00:00Z" }
GET /domains/{domain_id}/verify

Check domain verification status

Response

{ "id": "ver_1234567890", "domain": "example.com", "status": "verified", "verified_at": "2025-01-10T12:05:00Z", "expires_at": "2026-01-10T12:05:00Z" }
GET /domains

List all verified domains

Query Parameters

Parameter Type Description
limit integer Number of results (default: 20, max: 100)
offset integer Pagination offset

Subdomains

POST /subdomains

Create a new subdomain

Request Body

Parameter Type Description
domain_id * string ID of the verified domain
prefix * string Subdomain prefix (e.g., "api", "docs")
type * string Type: "static", "proxy", "status", "redirect"
config object Type-specific configuration

Response

{ "id": "sub_abc123", "domain_id": "dom_xyz789", "prefix": "api", "fqdn": "api.example.com.bond", "type": "proxy", "status": "active", "config": { "target": "https://backend.example.com", "headers": { "X-Verified-Domain": "example.com" } }, "ssl_status": "active", "created_at": "2025-01-10T12:00:00Z" }
PUT /subdomains/{subdomain_id}

Update subdomain configuration

DELETE /subdomains/{subdomain_id}

Delete a subdomain

Analytics

GET /analytics/usage

Get usage statistics for your subdomains

Query Parameters

Parameter Type Description
subdomain_id string Filter by specific subdomain
start_date string Start date (ISO 8601)
end_date string End date (ISO 8601)
granularity string "hour", "day" (default), "month"

Response

{ "period": { "start": "2025-01-01T00:00:00Z", "end": "2025-01-10T23:59:59Z" }, "metrics": { "requests": 45678, "bandwidth_gb": 123.45, "unique_visitors": 8901, "avg_response_time_ms": 87 }, "time_series": [ { "timestamp": "2025-01-10T00:00:00Z", "requests": 5432, "bandwidth_gb": 12.34 } ] }

Webhooks

Configure webhooks to receive real-time notifications about events in your account.

Available Events

  • domain.verified - Domain verification completed
  • domain.expired - Domain verification expired
  • subdomain.created - New subdomain created
  • subdomain.updated - Subdomain configuration changed
  • subdomain.deleted - Subdomain removed
  • ssl.issued - SSL certificate issued
  • ssl.renewed - SSL certificate renewed

Webhook Payload

{ "id": "evt_123456", "type": "domain.verified", "created_at": "2025-01-10T12:00:00Z", "data": { "domain_id": "dom_xyz789", "domain": "example.com", "verified_at": "2025-01-10T12:00:00Z" } }

Webhook Security

All webhook requests include a signature in the X-ComBond-Signature header. Verify this signature using your webhook secret:

const crypto = require('crypto'); function verifyWebhook(payload, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); }

Error Handling

com.bond uses conventional HTTP response codes to indicate the success or failure of an API request.

Code Meaning
200 Success - The request completed successfully
201 Created - A new resource was created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid API key
403 Forbidden - Valid key but insufficient permissions
404 Not Found - Resource doesn't exist
429 Too Many Requests - Rate limit exceeded
500 Server Error - Something went wrong on our end

Error Response Format

{ "error": { "type": "invalid_request", "message": "The domain field is required", "code": "missing_parameter", "param": "domain" } }

SDKs & Libraries

Official SDKs are available for popular languages:

Node.js

npm install @combond/node

Python

pip install combond

Ruby

gem install combond

PHP

composer require combond/php

API Support

Need help with the API?