---
title: "Domains"
description: "Register and verify domain ownership through the TurboPentest API. Verify a root domain once and every subdomain is automatically covered for pentesting."
canonical: https://turbopentest.com/docs/api/domains
source: "TurboPentest Docs"
---

# Domains

TurboPentest uses a top-level domain (TLD) model for verification. You register and verify a root domain, and all subdomains are automatically covered for pentesting.

## List domains

```
GET /api/tlds
```

Returns all top-level domains registered for your account, along with their verification status and associated targets.

**Response** `200 OK`

```json
[
  {
    "id": "1f0c9c4e-7a2b-4d3e-9f1a-2b3c4d5e6f70",
    "domain": "example.com",
    "status": "verified",
    "verificationToken": "abc123def456",
    "verifiedAt": "2026-01-10T08:00:00Z",
    "expiresAt": "2027-01-10T08:00:00Z",
    "targets": [
      { "id": "tgt_001", "fqdn": "app.example.com" },
      { "id": "tgt_002", "fqdn": "api.example.com" }
    ]
  }
]
```

## Register a domain

```
POST /api/tlds
```

Registers a new top-level domain and returns a verification token. You must register the root domain - subdomains are not accepted.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domain` | string | Yes | The top-level domain to register (e.g. `example.com`) |

**Response** `201 Created`

```json
{
  "id": "2a1b3c4d-5e6f-4708-9a0b-1c2d3e4f5a60",
  "domain": "newsite.com",
  "status": "pending",
  "verificationToken": "xyz789token",
  "verifiedAt": null,
  "expiresAt": null
}
```

After registering, add a DNS TXT record with the value `turbopentest-verify=<verificationToken>` to your domain, then trigger verification.

**Error responses**

| Status | Condition |
|--------|-----------|
| `400` | Invalid domain format |
| `400` | Subdomain provided instead of top-level domain |
| `409` | Domain already registered for your account |

## Get domain details

```
GET /api/tlds/{id}
```

Returns full details for a specific domain, including all associated targets. Note that this endpoint returns the raw asset record, so the domain name is in the `identifier` field.

**Response** `200 OK`

```json
{
  "id": "1f0c9c4e-7a2b-4d3e-9f1a-2b3c4d5e6f70",
  "identifier": "example.com",
  "status": "verified",
  "verificationToken": "abc123def456",
  "verifiedAt": "2026-01-10T08:00:00Z",
  "expiresAt": "2027-01-10T08:00:00Z",
  "targets": [
    {
      "id": "tgt_001",
      "fqdn": "app.example.com",
      "repoUrl": "https://github.com/org/app",
      "createdAt": "2026-01-12T09:00:00Z"
    }
  ]
}
```

## Remove a domain

```
DELETE /api/tlds/{id}
```

Removes a domain and all its associated targets. Any active schedules under the domain's targets are automatically paused before deletion.

**Response** `200 OK`

```json
{
  "deleted": true
}
```

## Verify domain ownership

```
POST /api/tlds/{id}/verify
```

Triggers a DNS TXT record lookup to verify domain ownership. Before calling this endpoint, ensure you have added the verification TXT record to your domain's DNS.

**Response** `200 OK`

```json
{
  "id": "2a1b3c4d-5e6f-4708-9a0b-1c2d3e4f5a60",
  "domain": "newsite.com",
  "status": "verified",
  "verificationToken": "xyz789token",
  "verifiedAt": "2026-01-15T12:00:00Z",
  "expiresAt": "2027-01-15T12:00:00Z"
}
```

Verification is valid for 1 year. You will receive reminder emails at 60, 30, and 7 days before expiration. When verification expires, all scheduled pentests under that domain are automatically paused.

**Error responses**

| Status | Condition |
|--------|-----------|
| `400` | Domain is already verified and not expired |
| `404` | Domain not found |
| `422` | DNS lookup failed or verification TXT record not found |

If verification fails, the response includes the expected TXT record value and (when applicable) the records that were found, to help you troubleshoot.