# domains 6 routes, from the API’s own OpenAPI document. URL: https://docs.qaldy.com/reference/api/domains/ 6 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/). ## Routes | Method | Path | What it does | |---|---|---| | [[GET]] | [`/​v1/​apps/​{id}/​domains`](#get-v1-apps-id-domains) | The custom hostnames of an app or site, with the DNS records to add | | [[POST]] | [`/​v1/​apps/​{id}/​domains`](#post-v1-apps-id-domains) | Attach a hostname to an app or site (owner); returns the DNS records to add | | [[DELETE]] | [`/​v1/​apps/​{id}/​domains/​{domainId}`](#delete-v1-apps-id-domains-domainid) | Remove a hostname from an app or site (owner) | | [[POST]] | [`/​v1/​apps/​{id}/​domains/​{domainId}/​check`](#post-v1-apps-id-domains-domainid-check) | Look at DNS and the certificate now; on a failed hostname, start over | | [[GET]] | [`/​v1/​workspaces/​{ws}/​domains`](#get-v1-workspaces-ws-domains) | Every custom hostname in the workspace on an app you can open | | [[POST]] | [`/​v1/​workspaces/​{ws}/​sender-domain/​check`](#post-v1-workspaces-ws-sender-domain-check) | Read the public DNS of the domain apps send email from (builders) | ## Reference ### [[GET]] `/v1/apps/{id}/domains` The custom hostnames of an app or site, with the DNS records to add. - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** `can_view`. Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `id` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `appId` | string | yes | | | `available` | boolean | yes | | | `unavailable` | object or null | yes | | | `unavailable.code` | "not_configured" · "disabled_for_workspace" | yes | | | `unavailable.message` | string | yes | up to 400 characters | | `unavailable.hint` | string | yes | up to 400 characters | | `canManage` | boolean | yes | | | `cnameTarget` | string or null | yes | | | `domains` | object[] | yes | | | `domains[].id` | string | yes | 1 to 64 characters | | `domains[].appId` | string | yes | 1 to 64 characters | | `domains[].hostname` | string | yes | 4 to 253 characters | | `domains[].state` | "pending_ownership" · "pending_dns" · "pending_cert" · "active" · "failed" | yes | | | `domains[].waiting` | "txt_missing" · "txt_mismatch" · "dns_unreachable" · "cname_missing" · "cname_elsewhere" · "cert_validating" · "cert_issuing" · "cert_deploying" · … or null | yes | | | `domains[].observed` | string or null | yes | up to 300 characters | | `domains[].providerNotes` | string[] | yes | up to 5 items | | `domains[].failure` | "timed_out" · "blocked" · "cert_failed" · "removed_upstream" · "provider_error" · null or null | yes | | | `domains[].records` | object[] | yes | | | `domains[].url` | string or null | yes | | | `domains[].createdAt` | string (date-time) | yes | | | `domains[].stateSince` | string (date-time) | yes | | | `domains[].lastCheckedAt` | string (date-time) or null | yes | | | `domains[].deadlineAt` | string (date-time) or null | yes | | | `domains[].createdBy` | object or null | yes | | | `limits` | object | yes | | | `limits.perApp` | integer | yes | at least 1 | | `limits.perWorkspace` | integer | yes | at least 1 | | `limits.usedInWorkspace` | integer | yes | at least 0 | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/apps/{id}/domains` Attach a hostname to an app or site (owner); returns the DNS records to add. - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** owner (a workspace admin owns every app). Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `id` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `hostname` | string | yes | 1 to 300 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `id` | string | yes | 1 to 64 characters | | `appId` | string | yes | 1 to 64 characters | | `hostname` | string | yes | 4 to 253 characters | | `state` | "pending_ownership" · "pending_dns" · "pending_cert" · "active" · "failed" | yes | | | `waiting` | "txt_missing" · "txt_mismatch" · "dns_unreachable" · "cname_missing" · "cname_elsewhere" · "cert_validating" · "cert_issuing" · "cert_deploying" · … or null | yes | | | `observed` | string or null | yes | up to 300 characters | | `providerNotes` | string[] | yes | up to 5 items | | `failure` | "timed_out" · "blocked" · "cert_failed" · "removed_upstream" · "provider_error" · null or null | yes | | | `records` | object[] | yes | | | `records[].purpose` | "ownership" · "route" · "certificate" | yes | | | `records[].type` | "TXT" · "CNAME" | yes | | | `records[].name` | string | yes | 1 to 300 characters | | `records[].value` | string | yes | 1 to 600 characters | | `records[].seen` | "done" · "waiting" · "unknown" | yes | | | `url` | string or null | yes | | | `createdAt` | string (date-time) | yes | | | `stateSince` | string (date-time) | yes | | | `lastCheckedAt` | string (date-time) or null | yes | | | `deadlineAt` | string (date-time) or null | yes | | | `createdBy` | object or null | yes | | | `createdBy.id` | string | yes | | | `createdBy.name` | string | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[DELETE]] `/v1/apps/{id}/domains/{domainId}` Remove a hostname from an app or site (owner). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** owner. Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `id` | path | string | yes | 1 to 128 characters | | `domainId` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `ok` | true | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/apps/{id}/domains/{domainId}/check` Look at DNS and the certificate now; on a failed hostname, start over. - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** `can_edit`. Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `id` | path | string | yes | 1 to 128 characters | | `domainId` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `id` | string | yes | 1 to 64 characters | | `appId` | string | yes | 1 to 64 characters | | `hostname` | string | yes | 4 to 253 characters | | `state` | "pending_ownership" · "pending_dns" · "pending_cert" · "active" · "failed" | yes | | | `waiting` | "txt_missing" · "txt_mismatch" · "dns_unreachable" · "cname_missing" · "cname_elsewhere" · "cert_validating" · "cert_issuing" · "cert_deploying" · … or null | yes | | | `observed` | string or null | yes | up to 300 characters | | `providerNotes` | string[] | yes | up to 5 items | | `failure` | "timed_out" · "blocked" · "cert_failed" · "removed_upstream" · "provider_error" · null or null | yes | | | `records` | object[] | yes | | | `records[].purpose` | "ownership" · "route" · "certificate" | yes | | | `records[].type` | "TXT" · "CNAME" | yes | | | `records[].name` | string | yes | 1 to 300 characters | | `records[].value` | string | yes | 1 to 600 characters | | `records[].seen` | "done" · "waiting" · "unknown" | yes | | | `url` | string or null | yes | | | `createdAt` | string (date-time) | yes | | | `stateSince` | string (date-time) | yes | | | `lastCheckedAt` | string (date-time) or null | yes | | | `deadlineAt` | string (date-time) or null | yes | | | `createdBy` | object or null | yes | | | `createdBy.id` | string | yes | | | `createdBy.name` | string | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[GET]] `/v1/workspaces/{ws}/domains` Every custom hostname in the workspace on an app you can open. - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** member. Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `available` | boolean | yes | | | `unavailable` | object or null | yes | | | `unavailable.code` | "not_configured" · "disabled_for_workspace" | yes | | | `unavailable.message` | string | yes | up to 400 characters | | `unavailable.hint` | string | yes | up to 400 characters | | `cnameTarget` | string or null | yes | | | `domains` | object[] | yes | | | `domains[].id` | string | yes | 1 to 64 characters | | `domains[].appId` | string | yes | 1 to 64 characters | | `domains[].hostname` | string | yes | 4 to 253 characters | | `domains[].state` | "pending_ownership" · "pending_dns" · "pending_cert" · "active" · "failed" | yes | | | `domains[].waiting` | "txt_missing" · "txt_mismatch" · "dns_unreachable" · "cname_missing" · "cname_elsewhere" · "cert_validating" · "cert_issuing" · "cert_deploying" · … or null | yes | | | `domains[].observed` | string or null | yes | up to 300 characters | | `domains[].providerNotes` | string[] | yes | up to 5 items | | `domains[].failure` | "timed_out" · "blocked" · "cert_failed" · "removed_upstream" · "provider_error" · null or null | yes | | | `domains[].records` | object[] | yes | | | `domains[].url` | string or null | yes | | | `domains[].createdAt` | string (date-time) | yes | | | `domains[].stateSince` | string (date-time) | yes | | | `domains[].lastCheckedAt` | string (date-time) or null | yes | | | `domains[].deadlineAt` | string (date-time) or null | yes | | | `domains[].createdBy` | object or null | yes | | | `domains[].appName` | string | yes | | | `domains[].appSlug` | string | yes | | | `domains[].kind` | "app" · "site" | yes | | | `limits` | object | yes | | | `limits.perWorkspace` | integer | yes | at least 1 | | `limits.usedInWorkspace` | integer | yes | at least 0 | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)). ### [[POST]] `/v1/workspaces/{ws}/sender-domain/check` Read the public DNS of the domain apps send email from (builders). - **Authentication:** the console’s session cookie. - **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token). - **Who:** builder. Not for tokens | Parameter | In | Type | Required | Notes | |---|---|---|---|---| | `ws` | path | string | yes | 1 to 128 characters | **Request body** (`application/json`) | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string | yes | 1 to 300 characters | | `provider` | "resend" · "postmark" · "other" | yes | | | `selector` | string | | up to 80 characters | **Response 200** | Field | Type | Required | Notes | |---|---|---|---| | `domain` | string | yes | | | `provider` | "resend" · "postmark" · "other" | yes | | | `checkedAt` | string (date-time) | yes | | | `checks` | object[] | yes | | | `checks[].id` | "dkim" · "spf" · "return_path" · "dmarc" | yes | | | `checks[].status` | "found" · "missing" · "unclear" · "skipped" | yes | | | `checks[].name` | string | yes | up to 300 characters | | `checks[].found` | string or null | yes | up to 200 characters | | `checks[].note` | "dns_unreachable" · "selector_needed" · "other_policy" · "weak_policy" · null or null | yes | | Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).