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

# Get Proxy

Get proxy information for an organization. Returns CloudFront distribution info and connection status needed for the two-part DNS configuration flow.

Supports:

* **Apex domains** (example.com)
* **WWW subdomains** ([www.example.com](http://www.example.com))
* **Custom subdomains** (shop.example.com, blog.example.com, etc.)

## Path Parameters

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `org_id`  | string | Yes      | Clerk organization slug (e.g., company-name-123456) |

## Example Request

```bash theme={null}
curl -X GET https://searchcompany-main.up.railway.app/api/domain/get-proxy/my-company-123456 \
  -H "Authorization: Bearer $TOKEN"
```

## Example Response (WWW Subdomain - Deployed)

```json theme={null}
{
  "has_proxy": true,
  "proxy_status": "DEPLOYED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "abc123.vercel-dns.com",
  "original_www_cname": "abc123.vercel-dns.com",
  "custom_domain": "www.example.com",
  "domain_type": "subdomain",
  "naked_domain": "example.com",
  "subdomain_label": "www",
  "apex_gateway_ips": null
}
```

## Example Response (Custom Subdomain - shop.example.com)

```json theme={null}
{
  "has_proxy": true,
  "proxy_status": "DEPLOYED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "shop-origin.example.com",
  "original_www_cname": "shop-origin.example.com",
  "custom_domain": "shop.example.com",
  "domain_type": "subdomain",
  "naked_domain": "example.com",
  "subdomain_label": "shop",
  "apex_gateway_ips": null
}
```

## Example Response (Apex Domain - Ready for Part 2)

```json theme={null}
{
  "has_proxy": true,
  "proxy_status": "SSL_VALIDATED",
  "cloudfront_domain": "d123abc456def.cloudfront.net",
  "distribution_id": "E123ABC456",
  "certificate_arn": "arn:aws:acm:us-east-1:123456:certificate/abc-123",
  "origin_cname": "104.20.22.37",
  "original_www_cname": null,
  "custom_domain": "example.com",
  "domain_type": "apex",
  "naked_domain": "example.com",
  "subdomain_label": "@",
  "original_apex_a_records": ["104.20.22.37", "172.66.165.95"],
  "apex_gateway_ips": ["15.197.156.92", "76.223.83.76"]
}
```

## Example Response (No Proxy)

```json theme={null}
{
  "has_proxy": false,
  "proxy_status": null,
  "cloudfront_domain": null,
  "distribution_id": null,
  "certificate_arn": null,
  "origin_cname": null,
  "original_www_cname": null,
  "custom_domain": null,
  "domain_type": "subdomain",
  "naked_domain": null,
  "subdomain_label": null,
  "apex_gateway_ips": null
}
```

## Response Fields

| Field                     | Type      | Description                                                                                        |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------- |
| `has_proxy`               | boolean   | Whether a proxy has been set up                                                                    |
| `proxy_status`            | string    | Current status in the flow (see below)                                                             |
| `cloudfront_domain`       | string    | CloudFront distribution domain                                                                     |
| `distribution_id`         | string    | AWS CloudFront distribution ID                                                                     |
| `certificate_arn`         | string    | AWS ACM certificate ARN (set after Part 1 completes)                                               |
| `origin_cname`            | string    | Original origin (CNAME or A record IP)                                                             |
| `original_www_cname`      | string    | Original CNAME before proxy (for subdomain disconnect)                                             |
| `custom_domain`           | string    | Customer's domain (e.g., [www.example.com](http://www.example.com), shop.example.com, example.com) |
| `domain_type`             | string    | `"subdomain"` or `"apex"`                                                                          |
| `naked_domain`            | string    | Naked domain (e.g., example.com)                                                                   |
| `subdomain_label`         | string    | DNS record host: `"www"`, `"shop"`, `"@"` for apex                                                 |
| `original_apex_a_records` | string\[] | Original A records for apex (for apex disconnect)                                                  |
| `apex_gateway_ips`        | string\[] | Gateway IPs for apex domains (used in Part 2 A records)                                            |

## Proxy Status Flow

```
PENDING_VALIDATION → SSL_VALIDATED → DEPLOYED
       ↓                   ↓              ↓
  Ready for          SSL cert        User completed
  Part 1             issued &        Part 2, fully
  (TXT record)       attached        operational
```

| Status               | Description                                  | UI State                           |
| -------------------- | -------------------------------------------- | ---------------------------------- |
| `PENDING_VALIDATION` | CloudFront created, ready for Part 1         | Show "Start SSL Validation" button |
| `SSL_VALIDATED`      | SSL attached to CloudFront, ready for Part 2 | Show "Connect Domain" button       |
| `DEPLOYED`           | Part 2 done, domain connected                | Show success state                 |

## Two-Part Flow (Works for All Domain Types)

**Part 1: Domain Verification (no downtime)**

1. Frontend calls `/start-certificate` to get TXT record
2. User adds TXT record via Entri
3. Frontend calls `/complete-certificate` to validate and issue cert
4. Let's Encrypt certificate is attached to CloudFront
5. Status becomes `SSL_VALIDATED`

**Part 2: DNS Switch (zero downtime)**

* **Subdomains (www, shop, blog)**: User adds `CNAME subdomain_label → cloudfront_domain` via Entri
* **Apex domains**: User adds `A @ → apex_gateway_ips` via Entri (2 A records)

## Domain Type Handling

| Domain Type | Example                                   | Part 2 Record             | subdomain\_label |
| ----------- | ----------------------------------------- | ------------------------- | ---------------- |
| Apex        | example.com                               | A @ → Gateway IPs         | `@`              |
| WWW         | [www.example.com](http://www.example.com) | CNAME www → CloudFront    | `www`            |
| Shop        | shop.example.com                          | CNAME shop → CloudFront   | `shop`           |
| Blog        | blog.example.com                          | CNAME blog → CloudFront   | `blog`           |
| Multi-level | api.v2.example.com                        | CNAME api.v2 → CloudFront | `api.v2`         |

## Why Apex Domains Need Gateway IPs

Apex/naked domains (example.com) cannot use CNAME records per DNS specification. We provide static IP addresses via AWS Global Accelerator that route to our proxy, which then forwards to CloudFront.

This works with **ALL DNS providers** (GoDaddy, Cloudflare, Vercel, Namecheap, etc.) because A records are universally supported.