---
title: "Add a domain"
method: POST
path: "/v1/domains/"
tags: ["domains"]
---

# Add a domain

`POST /v1/domains/`

## Request

- Base URL: `https://api.ethiack.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ethiack.com/v1/domains/`
- Auth: none declared

Create a pending DNS-verified domain.

Args:
    body (CreateDomainRequest): Creation payload.
    db (AsyncSession): Request-scoped database session.
    context (ActiveContext): Resolved caller identity and scope.

Returns:
    SuccessResponse: The legacy create envelope carrying the new id.

Raises:
    ValueError: The request named the checkbox kind (self-attestation
        is a portal action), no ``organization_id`` was given and the
        caller has no default organization, or ``value`` is not a
        domain. Answered 400.
    PermissionError: Cerbos denied the create.
    ConflictError: The org already has a DNS proof for this value.

## Request body

- CreateDomainRequest: Request body for ``POST /v1/domains/``. Attributes: value (str): The domain to claim (e.g. ``example.com``). Cleaned to its bare FQDN and lower-cased by the service. organization_id (int | None): Owning organization; defaults to the caller's own organization when omitted. kind (VerificationKind | None): Accepted only so a request for ``domain_checkbox`` can be refused with a pointer to the portal -- self-attestation is not available through the API. Omit it, or send ``domain_dns``.
  - `value` string, required
  - `organization_id` integer, nullable
  - `kind` 'domain_checkbox' | 'domain_dns' | 'ip_ip' | 'ip_checkbox': Discriminator for the :class:`Verification` hierarchy. Members: DOMAIN_CHECKBOX: Domain self-attestation (:class:`DomainCheckboxVerification`). DOMAIN_DNS: Domain DNS-record proof (:class:`DomainDNSVerification`). IP_IP: CIDR proof (:class:`IpIpVerification`) — the requester's source IP must fall within the verified CIDR (system-activated). IP_CHECKBOX: CIDR self-attestation (:class:`IpCheckboxVerification`).

## Response `201`

Successful Response

- SuccessResponse: Standard response for successful write operations. Matches the ``SuccessResponse`` contract from api-3. Attributes: code (int): HTTP status code. description (str): Human-readable result description. id (int | str | None): Created/affected resource ID. success (bool): Always ``True`` for successful responses.
  - `code` integer, required
  - `description` string, required
  - `id` union
    - integer
    - string
  - `success` boolean

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ethiack/apis/ethiack-api.md) - [All operations](https://skmtc.dev/ethiack/apis/ethiack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ethiack/apis/ethiack-api/revisions/4eaba89bfebf?raw)