> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API endpoints for custom domain management.

All endpoints are under `/v2/compute/domains` and require a valid Telnyx API key in the `Authorization` header.

## Create a custom domain

```http theme={null}
POST /v2/compute/domains
```

```json theme={null}
{
  "domain": "api.acme.com",
  "function_id": "0198c2c5-8f1e-7a3d-9b21-6e4a0d5f1c88"
}
```

**Response:** `201 Created`

```json theme={null}
{
  "data": {
    "record_type": "custom_domain",
    "id": "a1b2c3d4-...",
    "domain": "api.acme.com",
    "function_id": "0198c2c5-...",
    "verification_status": "pending_verification",
    "verification_token": "telnyx-verify=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "cert_status": "pending",
    "created_at": "2026-08-18T17:00:00.000Z",
    "updated_at": "2026-08-18T17:00:00.000Z"
  }
}
```

Add a DNS TXT record at `_telnyx-verification.api.acme.com` with the `verification_token` value, then call the verify endpoint.

**Errors:**

| Status | Meaning                                                                   |
| ------ | ------------------------------------------------------------------------- |
| 422    | Invalid domain format, invalid function\_id, or domain already registered |
| 401    | Unauthorized                                                              |

## List custom domains

```http theme={null}
GET /v2/compute/domains
```

Supports query filters:

| Parameter                     | Example        | Description                   |
| ----------------------------- | -------------- | ----------------------------- |
| `filter[verification_status]` | `verified`     | Filter by verification status |
| `filter[function_id]`         | `0198c2c5-...` | Filter by bound function      |
| `filter[domain]`              | `api.acme.com` | Filter by domain name         |

**Response:** `200 OK`

```json theme={null}
{
  "data": [
    {
      "record_type": "custom_domain",
      "id": "a1b2c3d4-...",
      "domain": "api.acme.com",
      "function_id": "0198c2c5-...",
      "verification_status": "verified",
      "verification_token": "telnyx-verify=...",
      "cert_status": "active",
      "created_at": "2026-08-18T17:00:00.000Z",
      "updated_at": "2026-08-18T17:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 1
  }
}
```

## Get a single domain

```http theme={null}
GET /v2/compute/domains/{id}
```

**Response:** `200 OK` with a single domain object.

## Verify domain ownership

```http theme={null}
POST /v2/compute/domains/{id}/actions/verify
```

Checks the DNS TXT record at `_telnyx-verification.<domain>` against the stored token.

**On success:** Deploys HTTP routing (Gateway + HTTPRoute + Ingress) to all clusters, marks domain as `verified`.

**On failure:** Marks as `verification_failed`.

**On DNS error:** Returns `503 Service Unavailable` — retry later.

**Response:** `200 OK` with updated domain object.

## Upload TLS certificate

```http theme={null}
PUT /v2/compute/domains/{id}/cert
```

```json theme={null}
{
  "cert_pem": "-----BEGIN CERTIFICATE-----\n...",
  "key_pem": "-----BEGIN PRIVATE KEY-----\n..."
}
```

**Prerequisite:** Domain must be `verified`.

Validates:

* Cert/key pair is valid PEM
* Cert covers the domain (SAN or CN match)
* Cert is currently valid (not expired, not yet valid)

On success: encrypts and stores the cert, deploys HTTPS routing via ECCP.

**Response:** `200 OK` with updated domain object (`cert_status: "active"`).

**Errors:**

| Status | Meaning                                                                                |
| ------ | -------------------------------------------------------------------------------------- |
| 422    | Invalid cert/key pair, cert doesn't cover domain, cert expired, or domain not verified |
| 503    | ECCP deploy failed — cert is stored but routing not updated                            |

## Delete a domain

```http theme={null}
DELETE /v2/compute/domains/{id}
```

Tears down routing resources (Gateway + HTTPRoute + Ingress + TLS Secret) from all clusters, then deletes the DB row.

If the bound function was already deleted (`function_id` is null), the domain is still deletable — routing cleanup is attempted but may be a no-op.

**Response:** `200 OK` with the deleted domain object.

## Status reference

### Verification status

| Value                  | Meaning                                 |
| ---------------------- | --------------------------------------- |
| `pending_verification` | Created, awaiting DNS TXT record        |
| `verified`             | DNS TXT verified, HTTP routing deployed |
| `verification_failed`  | TXT record not found or doesn't match   |

### Cert status

| Value           | Meaning                                                  |
| --------------- | -------------------------------------------------------- |
| `pending`       | No cert uploaded                                         |
| `deploying`     | Cert stored, ECCP deploy in progress                     |
| `active`        | HTTPS routing live                                       |
| `failed_deploy` | ECCP deploy failed — cert stored but routing not updated |

## Function deletion behavior

When a bound function is deleted, the domain's `function_id` becomes `null` (ON DELETE SET NULL). The domain still exists but cannot route. To fix: delete the domain and create a new one with the correct function.