Domains

See Custom domains for how verification works.

Add a domainCopy Anchor Link

POST /v1/domains.createDomain

Adds a custom domain to an environment and starts verifying it. The response lists the DNS records to create. The domain serves traffic once it's verified. Verification gives up after 24 hours without the right records.

Permissions: the key needs one of environment.*.create_domain, environment.<environment_id>.create_domain.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/domains.createDomain \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop",
    "app": "web",
    "environment": "production",
    "domain": "shop.example.com"
  }'

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

Error statuses: 400, 401, 403, 404, 409, 429, 500. See Errors for the codes behind them.

Get a domainCopy Anchor Link

POST /v1/domains.getDomain

Returns a domain with its verification status and DNS records.

Permissions: the key needs one of environment.*.read_domain, environment.<environment_id>.read_domain.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/domains.getDomain \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com"
  }'

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.

List domainsCopy Anchor Link

POST /v1/domains.listDomains

Returns the workspace's custom domains, a page at a time. Each filter works on its own.

Permissions: the key needs environment.*.read_domain.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/domains.listDomains \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "shop"
  }'

ResponseCopy Anchor Link

On success the status is 200 OK. The fields in data:

When pagination.hasMore is true, pass pagination.cursor as cursor to get the next page.

Error statuses: 400, 401, 403, 404, 429, 500, 503. See Errors for the codes behind them.

Verify a domain againCopy Anchor Link

POST /v1/domains.verifyDomain

Restarts verification, for example after you fixed a record of a failed domain. The domain goes back to pending and gets another 24 hours.

Permissions: the key needs one of environment.*.verify_domain, environment.<environment_id>.verify_domain.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/domains.verifyDomain \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com"
  }'

ResponseCopy Anchor Link

On success the status is 202 Accepted.

Error statuses: 400, 401, 403, 404, 412, 429, 500. See Errors for the codes behind them.

Remove a domainCopy Anchor Link

POST /v1/domains.deleteDomain

Removes a custom domain. It stops serving the app right away.

Permissions: the key needs one of environment.*.delete_domain, environment.<environment_id>.delete_domain.

RequestCopy Anchor Link

curl -X POST https://api.teral.dev/v1/domains.deleteDomain \
  -H "Authorization: Bearer $TERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com"
  }'

ResponseCopy Anchor Link

On success the status is 200 OK.

Error statuses: 400, 401, 403, 404, 429, 500. See Errors for the codes behind them.