Workspace: domains

Every hostname the workspace holds, the platform name included

GET /v1/workspace/domains · operation listDomains

Requires the batondeck:workspace:read permission (action workspace:read).

Responses

Status	Meaning
200	Every hostname the workspace holds, the platform name included
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "domains": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "hostname": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "custom_domain": {
            "type": "boolean"
          },
          "created_at": {
            "type": "number"
          },
          "updated_at": {
            "type": "number"
          }
        },
        "required": [
          "hostname",
          "kind",
          "status",
          "custom_domain",
          "created_at",
          "updated_at"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "domains"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/workspace/domains' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Add a custom domain, on a plan that carries custom_domain; answers the DNS records to create

POST /v1/workspace/domains · operation addCustomDomain

Requires the batondeck:workspace:admin permission (action domain:manage).

Refused while the workspace is suspended or on deletion hold.

Request body (application/json)

Field	Type	Required	Notes
hostname	string	yes	≥ 3 chars, ≤ 253 chars

Request schema

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string",
      "minLength": 3,
      "maxLength": 253
    }
  },
  "required": [
    "hostname"
  ],
  "additionalProperties": false
}

Responses

Status	Meaning
201	Add a custom domain, on a plan that carries custom_domain; answers the DNS records to create
400	The arguments did not validate.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

201 response schema

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "CNAME",
              "TXT"
            ]
          },
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "name",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "identities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "number"
    },
    "updated_at": {
      "type": "number"
    }
  },
  "required": [
    "hostname",
    "status",
    "reason",
    "records",
    "identities",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/workspace/domains' \
  -H "Authorization: Bearer $BATONDECK_API_KEY" \
  -H 'content-type: application/json' \
  -d @body.json

One custom domain: its status, the DNS records to create and what is still needed, read live

GET /v1/workspace/domains/{hostname} · operation getCustomDomain

Requires the batondeck:workspace:read permission (action workspace:read).

Parameters

Name	In	Type	Required	Notes
hostname	path	string	yes

Responses

Status	Meaning
200	One custom domain: its status, the DNS records to create and what is still needed, read live
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "CNAME",
              "TXT"
            ]
          },
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "name",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "identities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "number"
    },
    "updated_at": {
      "type": "number"
    }
  },
  "required": [
    "hostname",
    "status",
    "reason",
    "records",
    "identities",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

curl -X GET 'https://api.batondeck.com/v1/workspace/domains/:hostname' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Remove a custom domain no identity lives at; its certificate stops being served

DELETE /v1/workspace/domains/{hostname} · operation removeCustomDomain

Requires the batondeck:workspace:admin permission (action domain:remove).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
hostname	path	string	yes

Responses

Status	Meaning
204	Done. No body.
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

curl -X DELETE 'https://api.batondeck.com/v1/workspace/domains/:hostname' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"

Check the domain now instead of waiting for the five-minute poll, and record the result

POST /v1/workspace/domains/{hostname}/check · operation checkCustomDomain

Requires the batondeck:workspace:admin permission (action domain:manage).

Refused while the workspace is suspended or on deletion hold.

Parameters

Name	In	Type	Required	Notes
hostname	path	string	yes

Responses

Status	Meaning
200	Check the domain now instead of waiting for the five-minute poll, and record the result
401	No portal session, and no live API key.
403	The policy refused, or the request was cross-site.
404	No such resource, or none this session may see.

200 response schema

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "reason": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "CNAME",
              "TXT"
            ]
          },
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "name",
          "value"
        ],
        "additionalProperties": false
      }
    },
    "identities": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "number"
    },
    "updated_at": {
      "type": "number"
    }
  },
  "required": [
    "hostname",
    "status",
    "reason",
    "records",
    "identities",
    "created_at",
    "updated_at"
  ],
  "additionalProperties": false
}

curl -X POST 'https://api.batondeck.com/v1/workspace/domains/:hostname/check' \
  -H "Authorization: Bearer $BATONDECK_API_KEY"