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

# Domains

> Manage custom domains for your Stormkit environments

The Domains API allows you to add, list, and manage custom domains for your environments.

## Add Domain

<ParamField path="POST /v1/domains" type="endpoint">
  Add a custom domain to an environment.
</ParamField>

### Request Body

<ParamField body="domain" type="string" required>
  The domain name to add (e.g., "example.org")
</ParamField>

### Response

<ResponseField name="domainId" type="string">
  The unique identifier for the created domain
</ResponseField>

<ResponseField name="token" type="string">
  Verification token for DNS TXT record validation
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/domains' \
    -d '{ "domain": "example.org" }'
  ```

  ```json Response theme={null}
  {
    "domainId": "18914",
    "token": "AiX8xKhrGvsnwTTvT7yoxUFlTYzjn3bm"
  }
  ```
</CodeGroup>

***

## List Domains

<ParamField path="GET /v1/domains" type="endpoint">
  Retrieve all domains attached to an environment.
</ParamField>

### Query Parameters

<ParamField query="afterId" type="string">
  Pagination cursor for retrieving the next page of results
</ParamField>

<ParamField query="pageSize" type="string">
  Number of results to return (maximum: 250)
</ParamField>

<ParamField query="verified" type="string">
  Filter by verification status. Set to "true" to return only verified domains
</ParamField>

### Response

<ResponseField name="domains" type="array">
  Array of domain objects

  <Expandable title="Domain Object">
    <ResponseField name="id" type="string">
      Unique domain identifier
    </ResponseField>

    <ResponseField name="domainName" type="string">
      The domain name
    </ResponseField>

    <ResponseField name="verified" type="boolean">
      Whether the domain is verified (always true for self-hosted instances)
    </ResponseField>

    <ResponseField name="token" type="string">
      Verification token for DNS TXT record
    </ResponseField>

    <ResponseField name="customCert" type="object" optional>
      Custom SSL certificate information

      <Expandable title="Custom Certificate">
        <ResponseField name="value" type="string">
          Certificate value in PEM format
        </ResponseField>

        <ResponseField name="key" type="string">
          Private key in PEM format
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="hasNextPage" type="boolean">
      Whether more results are available
    </ResponseField>

    <ResponseField name="afterId" type="string" optional>
      Cursor for the next page
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/domains'
  ```

  ```json Response theme={null}
  {
    "domains": [
      {
        "id": "18914",
        "domainName": "example.org",
        "verified": false,
        "token": "AiX8xKhrGvsnwTTvT7yoxUFlTYzjn3bm"
      }
    ],
    "pagination": {
      "hasNextPage": false
    }
  }
  ```
</CodeGroup>

***

## Delete Domain

<ParamField path="DELETE /v1/domains" type="endpoint">
  Remove a domain by its ID.
</ParamField>

### Query Parameters

<ParamField query="id" type="string" required>
  The domain ID to delete
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the deletion was successful
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/domains?id=1501'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

## Update Custom Certificate

<ParamField path="PUT /v1/domains/cert" type="endpoint">
  Upload a custom SSL certificate for a domain.
</ParamField>

<Note>
  This endpoint is only available for Enterprise customers.
</Note>

### Request Body

<ParamField body="domainId" type="string" required>
  The ID of the domain
</ParamField>

<ParamField body="certKey" type="string" required>
  Private key in PEM format
</ParamField>

<ParamField body="certValue" type="string" required>
  Certificate value in PEM format
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the certificate was updated successfully
</ResponseField>

<Info>
  You can convert CRT files to PEM format using OpenSSL:

  ```bash theme={null}
  openssl x509 -in example_org.crt -out example_org.pem -outform PEM
  ```
</Info>

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/domains/cert' \
    -d '{
      "domainId": "2500",
      "certValue": "-----BEGIN CERTIFICATE-----\n...",
      "certKey": "-----BEGIN PRIVATE KEY-----\n..."
    }'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

## Delete Custom Certificate

<ParamField path="DELETE /v1/domains/cert" type="endpoint">
  Remove the custom SSL certificate from a domain.
</ParamField>

<Note>
  This endpoint is only available for Enterprise customers.
</Note>

### Query Parameters

<ParamField query="id" type="string" required>
  The domain ID
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the certificate was deleted successfully
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/domains/cert?id=2500'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>