# Domains API reference

Source: `@socra/domain-api@0.0.5` (DomainContract).

Domain discovery, account-owned verified Domains, and project-owned exact Hostnames.

## API surface

Base URL: `https://domain.socra.cloud`

## Domain availability

Current registrar availability and premium pricing for candidate internet domains.

### Search domain availability

`POST /v1/domain-availability/search`

#### Request body

- `domains` string[] (min items: 1; max items: 50), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "domains": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 253,
        "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
      }
    }
  },
  "required": [
    "domains"
  ]
}
```

#### Response

- `data` object[], required
  - `domain` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
  - `status` "available" | "unavailable" | "unknown", required
  - `premium` boolean, required
  - `premium_registration_price` number | null, required
  - `premium_renewal_price` number | null, required
  - `premium_transfer_price` number | null, required
  - `premium_restore_price` number | null, required
  - `icann_fee` number | null, required
  - `eap_fee` number | null, required
  - `currency` string (min length: 3; max length: 3), required
  - `error` string | null, required
- `checked_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "domain": {
            "type": "string",
            "minLength": 3,
            "maxLength": 253,
            "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "unavailable",
              "unknown"
            ]
          },
          "premium": {
            "type": "boolean"
          },
          "premium_registration_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_renewal_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_transfer_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "premium_restore_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "icann_fee": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "eap_fee": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "domain",
          "status",
          "premium",
          "premium_registration_price",
          "premium_renewal_price",
          "premium_transfer_price",
          "premium_restore_price",
          "icann_fee",
          "eap_fee",
          "currency",
          "error"
        ],
        "additionalProperties": false
      }
    },
    "checked_at": {}
  },
  "required": [
    "data",
    "checked_at"
  ],
  "additionalProperties": false
}
```

## Domain pricing

Cached registrar pricing by TLD, action, and duration. Prices are estimates until checkout.

### Quote domain pricing

`POST /v1/domain-pricing/quote`

#### Request body

- `tlds` string[] (min items: 1; max items: 50), required
- `action` "register" | "renew" | "transfer" | "reactivate", required
- `duration` integer (min: 1; max: 10), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "tlds": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 2,
        "maxLength": 127,
        "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)*[a-z]{2,63}$"
      }
    },
    "action": {
      "type": "string",
      "enum": [
        "register",
        "renew",
        "transfer",
        "reactivate"
      ]
    },
    "duration": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    }
  },
  "required": [
    "tlds",
    "action",
    "duration"
  ]
}
```

#### Response

- `data` object[], required
  - `tld` string (min length: 2; max length: 127; pattern: ^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)*[a-z]{2,63}$), required
  - `action` "register" | "renew" | "transfer" | "reactivate", required
  - `duration` integer (greater than: 0; max: 9007199254740991), required
  - `duration_type` "year", required
  - `price` number | null, required
  - `additional_cost` number | null, required
  - `total_price` number | null, required
  - `regular_price` number | null, required
  - `your_price` number | null, required
  - `promotion_price` number | null, required
  - `currency` string (min length: 3; max length: 3), required
  - `error` string | null, required
- `fetched_at` custom, required
- `expires_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tld": {
            "type": "string",
            "minLength": 2,
            "maxLength": 127,
            "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)*[a-z]{2,63}$"
          },
          "action": {
            "type": "string",
            "enum": [
              "register",
              "renew",
              "transfer",
              "reactivate"
            ]
          },
          "duration": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "duration_type": {
            "type": "string",
            "const": "year"
          },
          "price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "additional_cost": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "total_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "regular_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "your_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "promotion_price": {
            "anyOf": [
              {
                "type": "number",
                "minimum": 0
              },
              {
                "type": "null"
              }
            ]
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "tld",
          "action",
          "duration",
          "duration_type",
          "price",
          "additional_cost",
          "total_price",
          "regular_price",
          "your_price",
          "promotion_price",
          "currency",
          "error"
        ],
        "additionalProperties": false
      }
    },
    "fetched_at": {},
    "expires_at": {}
  },
  "required": [
    "data",
    "fetched_at",
    "expires_at"
  ],
  "additionalProperties": false
}
```

## Domains

An account-owned DNS namespace proven by a DNS TXT challenge.

### Resource schema

- `id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "pending" | "verified" | "disabled", required
- `verification_name` string, required
- `verification_value` string, required
- `verified_at` custom | null, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "verification_name": {
      "type": "string"
    },
    "verification_value": {
      "type": "string"
    },
    "verified_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "hostname",
    "status",
    "verification_name",
    "verification_value",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Create domain

`POST /v1/domains`

#### Request body

- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    }
  },
  "required": [
    "hostname"
  ]
}
```

#### Response

- `id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "pending" | "verified" | "disabled", required
- `verification_name` string, required
- `verification_value` string, required
- `verified_at` custom | null, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "verification_name": {
      "type": "string"
    },
    "verification_value": {
      "type": "string"
    },
    "verified_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "hostname",
    "status",
    "verification_name",
    "verification_value",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List domains

`GET /v1/domains`

#### Query parameters

- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), optional
- `status` "pending" | "verified" | "disabled", optional
- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  }
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
  - `status` "pending" | "verified" | "disabled", required
  - `verification_name` string, required
  - `verification_value` string, required
  - `verified_at` custom | null, required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "hostname": {
            "type": "string",
            "minLength": 3,
            "maxLength": 253,
            "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified",
              "disabled"
            ]
          },
          "verification_name": {
            "type": "string"
          },
          "verification_value": {
            "type": "string"
          },
          "verified_at": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "hostname",
          "status",
          "verification_name",
          "verification_value",
          "verified_at",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get domain

`GET /v1/domains/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "pending" | "verified" | "disabled", required
- `verification_name` string, required
- `verification_value` string, required
- `verified_at` custom | null, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "verification_name": {
      "type": "string"
    },
    "verification_value": {
      "type": "string"
    },
    "verified_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "hostname",
    "status",
    "verification_name",
    "verification_value",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Update domain

`PATCH /v1/domains/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `status` "pending" | "disabled", required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "disabled"
      ]
    }
  },
  "required": [
    "status"
  ]
}
```

#### Response

- `id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "pending" | "verified" | "disabled", required
- `verification_name` string, required
- `verification_value` string, required
- `verified_at` custom | null, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "verification_name": {
      "type": "string"
    },
    "verification_value": {
      "type": "string"
    },
    "verified_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "hostname",
    "status",
    "verification_name",
    "verification_value",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Verify domain DNS

`POST /v1/domains/{id}/verify`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "pending" | "verified" | "disabled", required
- `verification_name` string, required
- `verification_value` string, required
- `verified_at` custom | null, required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "disabled"
      ]
    },
    "verification_name": {
      "type": "string"
    },
    "verification_value": {
      "type": "string"
    },
    "verified_at": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "hostname",
    "status",
    "verification_name",
    "verification_value",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Delete domain

`DELETE /v1/domains/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

## Hostnames

An exact globally unique hostname claimed by one project beneath a verified account Domain.

### Resource schema

- `id` custom, required
- `domain_id` custom, required
- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "active" | "disabled", required
- `routing_target` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "domain_id": {},
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "routing_target": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "domain_id",
    "project_id",
    "hostname",
    "status",
    "routing_target",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Claim hostname

`POST /v1/hostnames`

#### Request body

- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    }
  },
  "required": [
    "project_id",
    "hostname"
  ]
}
```

#### Response

- `id` custom, required
- `domain_id` custom, required
- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "active" | "disabled", required
- `routing_target` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "domain_id": {},
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "routing_target": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "domain_id",
    "project_id",
    "hostname",
    "status",
    "routing_target",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### List hostnames

`GET /v1/hostnames`

#### Query parameters

- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), optional
- `domain_id` custom, optional
- `status` "active" | "disabled", optional
- `limit` integer (min: 1; max: 100), optional
- `after` string, optional

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "domain_id": {},
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "after": {
      "type": "string"
    }
  },
  "required": [
    "project_id"
  ]
}
```

#### Response

- `data` object[], required
  - `id` custom, required
  - `domain_id` custom, required
  - `project_id` custom, required
  - `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
  - `status` "active" | "disabled", required
  - `routing_target` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
  - `created_at` custom, required
  - `updated_at` custom, required
- `has_more` boolean, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {},
          "domain_id": {},
          "project_id": {},
          "hostname": {
            "type": "string",
            "minLength": 3,
            "maxLength": 253,
            "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled"
            ]
          },
          "routing_target": {
            "type": "string",
            "minLength": 3,
            "maxLength": 253,
            "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
          },
          "created_at": {},
          "updated_at": {}
        },
        "required": [
          "id",
          "domain_id",
          "project_id",
          "hostname",
          "status",
          "routing_target",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    },
    "has_more": {
      "type": "boolean"
    }
  },
  "required": [
    "data",
    "has_more"
  ],
  "additionalProperties": false
}
```

### Get hostname

`GET /v1/hostnames/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

- `id` custom, required
- `domain_id` custom, required
- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "active" | "disabled", required
- `routing_target` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "domain_id": {},
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "routing_target": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "domain_id",
    "project_id",
    "hostname",
    "status",
    "routing_target",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Update hostname

`PATCH /v1/hostnames/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Request body

- `status` "active" | "disabled", required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    }
  },
  "required": [
    "status"
  ]
}
```

#### Response

- `id` custom, required
- `domain_id` custom, required
- `project_id` custom, required
- `hostname` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `status` "active" | "disabled", required
- `routing_target` string (min length: 3; max length: 253; pattern: ^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$), required
- `created_at` custom, required
- `updated_at` custom, required

JSON Schema:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {},
    "domain_id": {},
    "project_id": {},
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "routing_target": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253,
      "pattern": "^(?=.{3,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
    },
    "created_at": {},
    "updated_at": {}
  },
  "required": [
    "id",
    "domain_id",
    "project_id",
    "hostname",
    "status",
    "routing_target",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}
```

### Release hostname

`DELETE /v1/hostnames/{id}`

#### Path parameters

- `id` custom, required

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}
```


#### Response

No response body.

---

Company: Socra — Multiply Your Judgment
Canonical URL: https://cloud.socra.com/docs/domain/reference/api