domains
6 routes, from the API’s own OpenAPI document.
6 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/apps/{id}/domains | The custom hostnames of an app or site, with the DNS records to add |
| 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} | Remove a hostname from an app or site (owner) |
| 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 | Every custom hostname in the workspace on an app you can open |
| 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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).
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_onlyfor 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).