Domains

List domains

Every domain of the project, default ones included, with the environment it serves or the domain it redirects to. A custom domain that is not active yet carries the DNS records to create (dnsRecords) and what is still wrong (verificationErrors).

Requires Viewer key or above (workspace.read)

Parameters

• projectIdstringin pathrequired

Responses

• 200The project's environments and domains.
  Response fields

  • environmentsobject[]required
    2 fields

    • idstringrequired
    • namestringrequired
  • domainsobject[]required
    12 fields

    • idstringrequired
    • environmentIdstringrequired
    • hostnamestringrequired
    • isDefaultbooleanrequired
    • status"pending" | "active" | "error"required
    • cloudflareHostnameIdstring | nullrequired
    • lastCheckedAtstring | nullrequired
    • createdAtstringrequired
    • environmentNamestringrequired
    • redirectobject | nullrequired
      3 fields

      • toDomainIdstringrequired
      • toHostnamestringrequired
      • statusCode301 | 302 | 307 | 308required
    • dnsRecordsobject[] | nullrequired
      4 fields

      • type"CNAME" | "ALIAS" | "TXT"required
      • namestringrequired
      • valuestringrequired
      • purpose"routing" | "ownership" | "certificate"required
    • verificationErrorsstring[]required
• 404No such project in this workspace.

curl "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Add a domain

Adds a custom domain that serves an environment (target.kind: environment) or redirects to another domain of the project (target.kind: redirect, with a 301, 302, 307 or 308). It starts pending: create the records in dnsRecords at your DNS provider, then call Refresh until it is active. HTTPS certificates are issued automatically.

Requires Developer key or above (domains.write)

Parameters

• projectIdstringin pathrequired

Body

• hostnamestringrequired

  at most 253 characters

• targetobjectrequired
  2 shapes

  One of:

  kind: "environment"

  • kind"environment"required
  • environmentIdstringrequired

    uuid

  kind: "redirect"

  • kind"redirect"required
  • toDomainIdstringrequired

    uuid

  • statusCode301 | 302 | 307 | 308required

Responses

• 201The created domain.
  Response fields

  • idstringrequired
  • environmentIdstringrequired
  • hostnamestringrequired
  • isDefaultbooleanrequired
  • status"pending" | "active" | "error"required
  • cloudflareHostnameIdstring | nullrequired
  • lastCheckedAtstring | nullrequired
  • createdAtstringrequired
  • environmentNamestringrequired
  • redirectobject | nullrequired
    3 fields

    • toDomainIdstringrequired
    • toHostnamestringrequired
    • statusCode301 | 302 | 307 | 308required
  • dnsRecordsobject[] | nullrequired
    4 fields

    • type"CNAME" | "ALIAS" | "TXT"required
    • namestringrequired
    • valuestringrequired
    • purpose"routing" | "ownership" | "certificate"required
  • verificationErrorsstring[]required
• 402Every custom domain your plan includes is in use (quota: custom_domains).

  Body: see Errors

• 404No such project in this workspace.
• 409That hostname is already in use.
• 422The target is an environment or a domain of another project, or a redirect to a domain that itself redirects.

curl -X POST "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "www.acme.dev",
    "target": {
      "kind": "environment",
      "environmentId": "9a1b7c3d-5e2f-4a8b-b6c4-2d8e1f9a5c31"
    }
  }'

Update a domain

Changes its hostname, its target, or both. A new hostname goes back to pending and needs its DNS records; the old one keeps serving until the new one is registered. Domains redirecting to this one follow it to its new environment.

Requires Developer key or above (domains.write)

Parameters

• projectIdstringin pathrequired
• domainIdstringin pathrequired

Body

• hostnamestring

  at most 253 characters

• targetobject
  2 shapes

  One of:

  kind: "environment"

  • kind"environment"required
  • environmentIdstringrequired

    uuid

  kind: "redirect"

  • kind"redirect"required
  • toDomainIdstringrequired

    uuid

  • statusCode301 | 302 | 307 | 308required

Responses

• 200The updated domain.
  Response fields

  • idstringrequired
  • environmentIdstringrequired
  • hostnamestringrequired
  • isDefaultbooleanrequired
  • status"pending" | "active" | "error"required
  • cloudflareHostnameIdstring | nullrequired
  • lastCheckedAtstring | nullrequired
  • createdAtstringrequired
  • environmentNamestringrequired
  • redirectobject | nullrequired
    3 fields

    • toDomainIdstringrequired
    • toHostnamestringrequired
    • statusCode301 | 302 | 307 | 308required
  • dnsRecordsobject[] | nullrequired
    4 fields

    • type"CNAME" | "ALIAS" | "TXT"required
    • namestringrequired
    • valuestringrequired
    • purpose"routing" | "ownership" | "certificate"required
  • verificationErrorsstring[]required
• 400An environment's default domain can't be renamed, moved or redirected.
• 404No such project or domain in this workspace.
• 409That hostname is already in use.
• 422The target breaks a rule (see Add a domain).
• 502The new hostname was refused; the domain keeps its old one.

curl -X PATCH "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "kind": "redirect",
      "toDomainId": "6e8a0c2e-4f6b-4d8e-a0c2-3b5d7f9e1a86",
      "statusCode": 308
    }
  }'

Delete a domain

The domain stops serving at once.

Requires Developer key or above (domains.write)

Parameters

• projectIdstringin pathrequired
• domainIdstringin pathrequired

Responses

• 204Deleted.
• 400Cannot delete an environment's default domain.
• 404Project or domain not found.
• 409Other domains redirect to this one.

curl -X DELETE "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"

Refresh a domain

Checks the domain's DNS and certificate again and returns its new status. Calls closer than 10 seconds apart for the same domain return the last result without checking again.

Requires Developer key or above (domains.write)

Parameters

• projectIdstringin pathrequired
• domainIdstringin pathrequired

Responses

• 200The domain, as of the check.
  Response fields

  • idstringrequired
  • environmentIdstringrequired
  • hostnamestringrequired
  • isDefaultbooleanrequired
  • status"pending" | "active" | "error"required
  • cloudflareHostnameIdstring | nullrequired
  • lastCheckedAtstring | nullrequired
  • createdAtstringrequired
  • environmentNamestringrequired
  • redirectobject | nullrequired
    3 fields

    • toDomainIdstringrequired
    • toHostnamestringrequired
    • statusCode301 | 302 | 307 | 308required
  • dnsRecordsobject[] | nullrequired
    4 fields

    • type"CNAME" | "ALIAS" | "TXT"required
    • namestringrequired
    • valuestringrequired
    • purpose"routing" | "ownership" | "certificate"required
  • verificationErrorsstring[]required
• 404No such project or domain in this workspace.

curl -X POST "https://api.hiraiship.com/api/v1/projects/$PROJECT_ID/domains/$DOMAIN_ID/refresh" \
  -H "Authorization: Bearer $HIRAISHIP_TOKEN"