Domains

List Domains

GET /api/v1/domains

Returns all domains in your organization.

curl -H "X-API-Key: sb_live_abc123def456" \
  https://api.surfbot.io/api/v1/domains

Response (200):

{
  "domains": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "domain": "example.com",
      "status": "active",
      "verification_status": "verified",
      "total_assets": 47,
      "finding_count": 0,
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

Get Domain

GET /api/v1/domains/:id

Returns a single domain with assets summary.

curl -H "X-API-Key: sb_live_abc123def456" \
  https://api.surfbot.io/api/v1/domains/550e8400-e29b-41d4-a716-446655440000

Response (200):

{
  "domain": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "status": "active",
    "verification": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "method": "dns",
      "challenge_token": "sb-verify-abc123",
      "status": "verified",
      "instructions": "Add a TXT record: _surfbot-verify.example.com with value: sb-verify-abc123",
      "verified_at": "2026-01-01T00:05:00Z",
      "expires_at": "2026-04-01T00:00:00Z"
    },
    "total_assets": 47,
    "finding_count": 0,
    "created_at": "2026-01-01T00:00:00Z"
  },
  "assets_summary": {
    "subdomain": 32,
    "ip": 8,
    "url": 7
  },
  "total_assets": 47
}

Add Domain

POST /api/v1/domains

Creates a new domain and generates a verification challenge. The API auto-verifies domains matching your business email — otherwise you'll need to verify via DNS or HTTP.

curl -X POST https://api.surfbot.io/api/v1/domains \
  -H "X-API-Key: sb_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "method": "dns"}'

Request Body:

Field	Type	Required	Description
`domain`	string	Yes	Root domain to monitor
`method`	string	No	Verification method: `dns` (default) or `http`

Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "domain": "example.com",
  "status": "active",
  "verification": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "method": "dns",
    "challenge_token": "sb-verify-abc123",
    "status": "pending",
    "instructions": "Add a TXT record: _surfbot-verify.example.com with value: sb-verify-abc123",
    "expires_at": "2026-04-01T00:00:00Z"
  },
  "total_assets": 0,
  "finding_count": 0,
  "created_at": "2026-03-15T10:00:00Z"
}

Domain quotas by plan:

Plan	Max Domains
Free	1
Hunter	5
Pro	25
Team	100
Enterprise	Unlimited

When the limit is reached, the API returns 403:

{
  "error": "domain_limit_reached",
  "message": "Your plan allows up to 1 domains. Upgrade to add more.",
  "limit": 1,
  "current": 1
}

Verify Domain

POST /api/v1/domains/:id/verify

Triggers a verification check. If already verified, returns the current status.

curl -X POST https://api.surfbot.io/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/verify \
  -H "X-API-Key: sb_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"method": "dns"}'

Request Body (optional):

Field	Type	Description
`method`	string	Switch verification method: `dns` or `http`. Generates a new challenge if changed.

Verification methods:

DNS: Add a TXT record _surfbot-verify.yourdomain.com with the challenge token value.
HTTP: Place a file at https://yourdomain.com/.well-known/surfbot-verify.txt containing the challenge token.
Email: Automatic for users with a business email matching the domain.

Success Response (200):

{
  "message": "domain verified successfully",
  "verification": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "method": "dns",
    "challenge_token": "sb-verify-abc123",
    "status": "verified",
    "instructions": "Add a TXT record: _surfbot-verify.example.com with value: sb-verify-abc123",
    "verified_at": "2026-01-01T00:05:00Z",
    "expires_at": "2026-04-01T00:00:00Z"
  }
}

Failure Response (422):

{
  "error": "verification failed",
  "details": "TXT record not found",
  "verification": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "method": "dns",
    "challenge_token": "sb-verify-abc123",
    "status": "pending",
    "instructions": "Add a TXT record: _surfbot-verify.example.com with value: sb-verify-abc123",
    "expires_at": "2026-04-01T00:00:00Z"
  }
}

Trigger Domain Scan

POST /api/v1/domains/:id/scan

Starts a scan for a verified domain. This is a convenience endpoint — see Scans for the full scan API.

curl -X POST https://api.surfbot.io/api/v1/domains/550e8400-e29b-41d4-a716-446655440000/scan \
  -H "X-API-Key: sb_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"type": "discovery"}'