Skip to content
GuvDocs

Domains

View as Markdown

Generated and custom domains, DNS instructions, ownership verification and certificates.

Operation Method and path
List domains GET /v1/projects/{project}/environments/{environment}/domains
Add a custom domain POST /v1/projects/{project}/environments/{environment}/domains
Get a domain GET /v1/projects/{project}/environments/{environment}/domains/{domain}
Point a domain at a different service PATCH /v1/projects/{project}/environments/{environment}/domains/{domain}
Remove a domain DELETE /v1/projects/{project}/environments/{environment}/domains/{domain}
Check DNS now POST /v1/projects/{project}/environments/{environment}/domains/{domain}/verify

List domains

Section titled “List domains”
GET /v1/projects/{project}/environments/{environment}/domains
  • Operation: listDomains
  • Scopes: projects:read
  • CLI: guv domains list
  • Paginated: ?limit= and ?cursor=

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.
service query string
status query DomainStatus

Responses

Status Meaning Body
200 OK A page of Domain objects. DomainList

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl https://api.guv.dev/v1/projects/shopfront/environments/production/domains \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "data": [
    {
      "id": "dom_01jbx2m9k7q4r8t5v6w3y0z1dm",
      "hostname": "www.primecarers.co.uk",
      "kind": "custom",
      "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
      "service_id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "status": "pending",
      "status_text": "Waiting for your DNS records. This usually takes a few minutes.",
      "apex": false,
      "wildcard": false,
      "dns_records": [
        {
          "type": "CNAME",
          "name": "www.primecarers.co.uk",
          "value": "prj-k7q4r8t5.edge.guv.run",
          "purpose": "routing",
          "status": "missing",
          "observed": []
        },
        {
          "type": "TXT",
          "name": "_guv-challenge.www.primecarers.co.uk",
          "value": "guv-verify=8f3a2c1d9e7b6a5f",
          "purpose": "ownership",
          "status": "ok",
          "observed": [
            "guv-verify=8f3a2c1d9e7b6a5f"
          ]
        }
      ],
      "registrar": {
        "name": "123-reg",
        "instructions_url": "https://guv.dev/docs/domains/123-reg"
      },
      "checks": {
        "dns": "pending",
        "ownership": "ok",
        "certificate": "pending",
        "live": "pending"
      },
      "certificate": null,
      "caa_warning": null,
      "error": null,
      "last_checked_at": "2026-10-23T14:10:00Z",
      "next_check_at": "2026-10-23T14:11:00Z",
      "created_at": "2026-10-23T14:00:00Z"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}

Add a custom domain

Section titled “Add a custom domain”
POST /v1/projects/{project}/environments/{environment}/domains

Returns the DNS records to create. Verification runs in the background; poll the domain or call verify.

  • Operation: addDomain
  • Scopes: projects:write
  • CLI: guv domains add
  • Approval: In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.
  • Idempotency-Key: required; supports ?dry_run=true

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.

Request body (application/json, required): DomainCreate

Field Type Description
hostname * string
service * string Service name or id that receives traffic.

Responses

Status Meaning Body
200 OK Dry run. Nothing was changed; this is what would happen. Plan
201 Created Created. Domain

Errors: 400, 401, 403, 404, 409, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X POST https://api.guv.dev/v1/projects/shopfront/environments/production/domains \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "hostname": "www.primecarers.co.uk",
  "service": "string"
}'

Example response

{
  "id": "dom_01jbx2m9k7q4r8t5v6w3y0z1dm",
  "hostname": "www.primecarers.co.uk",
  "kind": "custom",
  "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
  "service_id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
  "status": "pending",
  "status_text": "Waiting for your DNS records. This usually takes a few minutes.",
  "apex": false,
  "wildcard": false,
  "dns_records": [
    {
      "type": "CNAME",
      "name": "www.primecarers.co.uk",
      "value": "prj-k7q4r8t5.edge.guv.run",
      "purpose": "routing",
      "status": "missing",
      "observed": []
    },
    {
      "type": "TXT",
      "name": "_guv-challenge.www.primecarers.co.uk",
      "value": "guv-verify=8f3a2c1d9e7b6a5f",
      "purpose": "ownership",
      "status": "ok",
      "observed": [
        "guv-verify=8f3a2c1d9e7b6a5f"
      ]
    }
  ],
  "registrar": {
    "name": "123-reg",
    "instructions_url": "https://guv.dev/docs/domains/123-reg"
  },
  "checks": {
    "dns": "pending",
    "ownership": "ok",
    "certificate": "pending",
    "live": "pending"
  },
  "certificate": null,
  "caa_warning": null,
  "error": null,
  "last_checked_at": "2026-10-23T14:10:00Z",
  "next_check_at": "2026-10-23T14:11:00Z",
  "created_at": "2026-10-23T14:00:00Z"
}

Get a domain

Section titled “Get a domain”
GET /v1/projects/{project}/environments/{environment}/domains/{domain}
  • Operation: getDomain
  • Scopes: projects:read

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.
domain * path string Domain id (dom_…) or hostname.

Responses

Status Meaning Body
200 OK OK. Domain

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl https://api.guv.dev/v1/projects/shopfront/environments/production/domains/www.example.co.uk \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "id": "dom_01jbx2m9k7q4r8t5v6w3y0z1dm",
  "hostname": "www.primecarers.co.uk",
  "kind": "custom",
  "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
  "service_id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
  "status": "pending",
  "status_text": "Waiting for your DNS records. This usually takes a few minutes.",
  "apex": false,
  "wildcard": false,
  "dns_records": [
    {
      "type": "CNAME",
      "name": "www.primecarers.co.uk",
      "value": "prj-k7q4r8t5.edge.guv.run",
      "purpose": "routing",
      "status": "missing",
      "observed": []
    },
    {
      "type": "TXT",
      "name": "_guv-challenge.www.primecarers.co.uk",
      "value": "guv-verify=8f3a2c1d9e7b6a5f",
      "purpose": "ownership",
      "status": "ok",
      "observed": [
        "guv-verify=8f3a2c1d9e7b6a5f"
      ]
    }
  ],
  "registrar": {
    "name": "123-reg",
    "instructions_url": "https://guv.dev/docs/domains/123-reg"
  },
  "checks": {
    "dns": "pending",
    "ownership": "ok",
    "certificate": "pending",
    "live": "pending"
  },
  "certificate": null,
  "caa_warning": null,
  "error": null,
  "last_checked_at": "2026-10-23T14:10:00Z",
  "next_check_at": "2026-10-23T14:11:00Z",
  "created_at": "2026-10-23T14:00:00Z"
}

Point a domain at a different service

Section titled “Point a domain at a different service”
PATCH /v1/projects/{project}/environments/{environment}/domains/{domain}
  • Operation: updateDomain
  • Scopes: projects:write
  • Approval: In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.
  • Idempotency-Key: required; supports ?dry_run=true
  • Concurrency: send the ETag you read as If-Match

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.
domain * path string Domain id (dom_…) or hostname.

Request body (application/json, required): DomainUpdate

Field Type Description
service string

Responses

Status Meaning Body
200 OK OK. With dry_run=true: a Plan (application/vnd.guv.plan+json) and nothing changes. Domain

Errors: 400, 401, 403, 404, 409, 412, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X PATCH https://api.guv.dev/v1/projects/shopfront/environments/production/domains/www.example.co.uk \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "service": "string"
}'

Example response

{
  "id": "dom_01jbx2m9k7q4r8t5v6w3y0z1dm",
  "hostname": "www.primecarers.co.uk",
  "kind": "custom",
  "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
  "service_id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
  "status": "pending",
  "status_text": "Waiting for your DNS records. This usually takes a few minutes.",
  "apex": false,
  "wildcard": false,
  "dns_records": [
    {
      "type": "CNAME",
      "name": "www.primecarers.co.uk",
      "value": "prj-k7q4r8t5.edge.guv.run",
      "purpose": "routing",
      "status": "missing",
      "observed": []
    },
    {
      "type": "TXT",
      "name": "_guv-challenge.www.primecarers.co.uk",
      "value": "guv-verify=8f3a2c1d9e7b6a5f",
      "purpose": "ownership",
      "status": "ok",
      "observed": [
        "guv-verify=8f3a2c1d9e7b6a5f"
      ]
    }
  ],
  "registrar": {
    "name": "123-reg",
    "instructions_url": "https://guv.dev/docs/domains/123-reg"
  },
  "checks": {
    "dns": "pending",
    "ownership": "ok",
    "certificate": "pending",
    "live": "pending"
  },
  "certificate": null,
  "caa_warning": null,
  "error": null,
  "last_checked_at": "2026-10-23T14:10:00Z",
  "next_check_at": "2026-10-23T14:11:00Z",
  "created_at": "2026-10-23T14:00:00Z"
}

Remove a domain

Section titled “Remove a domain”
DELETE /v1/projects/{project}/environments/{environment}/domains/{domain}
  • Operation: removeDomain
  • Scopes: projects:write
  • Approval: In environments with protection turned on (usually production), changes by agents and by roles outside approver_roles return approval_required.
  • Idempotency-Key: required; supports ?dry_run=true
  • Concurrency: send the ETag you read as If-Match

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.
domain * path string Domain id (dom_…) or hostname.

Responses

Status Meaning Body
200 OK Dry run. Nothing was changed; this is what would happen. Plan
204 No Content Done. No body. none

Errors: 400, 401, 403, 404, 409, 412, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X DELETE https://api.guv.dev/v1/projects/shopfront/environments/production/domains/www.example.co.uk \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Check DNS now

Section titled “Check DNS now”
POST /v1/projects/{project}/environments/{environment}/domains/{domain}/verify
  • Operation: verifyDomain
  • Scopes: projects:write
  • CLI: guv domains verify
  • Idempotency-Key: required

Parameters

Name In Type Description
project * path string Project id (prj_…) or slug (resolved in the Guv-Workspace workspace, or the caller’s default).
environment * path string Environment id (env_…) or name.
domain * path string Domain id (dom_…) or hostname.

Responses

Status Meaning Body
200 OK OK. Domain

Errors: 400, 401, 403, 404, 409, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X POST https://api.guv.dev/v1/projects/shopfront/environments/production/domains/www.example.co.uk/verify \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Example response

{
  "id": "dom_01jbx2m9k7q4r8t5v6w3y0z1dm",
  "hostname": "www.primecarers.co.uk",
  "kind": "custom",
  "environment_id": "env_01jbx2m9k7q4r8t5v6w3y0z1en",
  "service_id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
  "status": "pending",
  "status_text": "Waiting for your DNS records. This usually takes a few minutes.",
  "apex": false,
  "wildcard": false,
  "dns_records": [
    {
      "type": "CNAME",
      "name": "www.primecarers.co.uk",
      "value": "prj-k7q4r8t5.edge.guv.run",
      "purpose": "routing",
      "status": "missing",
      "observed": []
    },
    {
      "type": "TXT",
      "name": "_guv-challenge.www.primecarers.co.uk",
      "value": "guv-verify=8f3a2c1d9e7b6a5f",
      "purpose": "ownership",
      "status": "ok",
      "observed": [
        "guv-verify=8f3a2c1d9e7b6a5f"
      ]
    }
  ],
  "registrar": {
    "name": "123-reg",
    "instructions_url": "https://guv.dev/docs/domains/123-reg"
  },
  "checks": {
    "dns": "pending",
    "ownership": "ok",
    "certificate": "pending",
    "live": "pending"
  },
  "certificate": null,
  "caa_warning": null,
  "error": null,
  "last_checked_at": "2026-10-23T14:10:00Z",
  "next_check_at": "2026-10-23T14:11:00Z",
  "created_at": "2026-10-23T14:00:00Z"
}