The Root Document

Every response follows the same structure, known as the root document. The main data structure, known as a resource, is nested under a data field. If you request a collection of resources, the data field will be an array of those resources. If you request a single resource, the data field will be equal to that resource.

If there is an error, the error field will be present, and the data field will be present and null.

Attributes
  • data
    object | null

    The root resource. If fetching a collection, this will be an array of resource objects.

  • includes
    object
    optional

    Includes fields. The key will be the name of the included item passed. All values of include fields will be a full resource structure. (i.e. including environments will embed full environment objects by ID)

  • meta
    object
    optional

    Meta fields. The key will be equal to the name of the meta field provided. Values of meta fields will vary based on the resource. These values are injected into the data object(s).

  • error
    object
    optional

    An error object, if there was a problem with the request.

Error
{
  "error": {
    "status": 401,
    "code": "401.auth_invalid",
    "title": "no auth header"
  },
  "data": null
}
Sample Root Document (Single Environment)
{
  "data": {
    "data": {
      "id": "5b9c2a77b6393d0001eb45fd",
      "name": "Demo Name",
      "cluster": "development",
      "about": {
        "description": "",
        "favorite": false
      },
      "creator": {
        "id": "5b9c2a77b6393d0001eb45fd",
        "type": "account"
      },
      "hub_id": "5b9c2a77b6393d0001eb45fd",
      "state": {
        "current": "live",
        "changed": "2022-09-14T21:39:03.096Z"
      },
      "events": {
        "created": "2022-09-14T21:39:03.096Z",
        "updated": "2022-09-14T21:39:03.096Z",
        "deleted": "2022-09-14T21:39:03.096Z"
      },
      "features": {
        "legacy_networking": false
      },
      "services": {
        "discovery": {
          "enable": true,
          "container_id": "5b9c2a77b6393d0001eb45fd",
          "high_availability": false,
          "config": {}
        },
        "vpn": {
          "enable": true,
          "container_id": "5b9c2a77b6393d0001eb45fd",
          "high_availability": false,
          "config": {
            "auth": {
              "webhook": null,
              "cycle_accounts": true,
              "vpn_accounts": true
            },
            "allow_internet": true
          }
        },
        "loadbalancer": {
          "enable": true,
          "container_id": "5b9c2a77b6393d0001eb45fd",
          "high_availability": true,
          "config": null
        }
      },
      "private_network": {
        "vxlan_tag": 6485,
        "subnet": "21",
        "legacy": null,
        "ipv6": {
          "ip": "fd00::21:0:0:0",
          "cidr": "fd00::21:0:0:0/96"
        }
      },
      "meta": {
        "containers": [
          {
            "id": "5b9c2a77b6393d0001eb45fd",
            "name": "Demo Name",
            "state": {
              "changed": "2020-12-29T07:42:30.378Z",
              "current": "running",
              "desired": "running"
            },
            "image": {
              "id": "5b9c2a77b6393d0001eb45fd",
              "service": null
            },
            "environment": {
              "id": "5b9c2a77b6393d0001eb45fd",
              "cluster": "production",
              "container_subnet": "1234",
              "ipv6": {
                "ip": "fd00::ef1:1834:0:0",
                "cidr": "fd00::ef1:1834:0:0/96"
              },
              "legacy": null
            }
          },
          {
            "id": "5b9c2a77b6393d0001eb45fd",
            "name": "Demo Name",
            "state": {
              "changed": "2020-12-29T07:42:27.51Z",
              "current": "running",
              "desired": "running"
            },
            "image": {
              "id": "5b9c2a77b6393d0001eb45fd",
              "service": null
            },
            "environment": {
              "id": "5b9c2a77b6393d0001eb45fd",
              "cluster": "production",
              "container_subnet": "1234",
              "ipv6": {
                "ip": "fd00::ef1:1834:0:0",
                "cidr": "fd00::ef1:1834:0:0/96"
              },
              "legacy": null
            }
          }
        ],
        "containers_count": {
          "state": {
            "new": 0,
            "starting": 0,
            "running": 8,
            "stopping": 0,
            "stopped": 3,
            "deleting": 0,
            "deleted": 0,
            "reimaging": 0
          },
          "total": 11,
          "available": 11
        },
        "instances_count": {
          "state": {
            "new": 0,
            "starting": 0,
            "reimaging": 0,
            "running": 12,
            "migrating": 0,
            "stopping": 0,
            "stopped": 7,
            "failed": 0,
            "deleting": 0,
            "deleted": 0
          },
          "total": 19,
          "available": 19
        }
      }
    },
    "includes": {
      "creators": {
        "accounts": {
          "5b9c2a77b6393d0001eb45fd": {
            "id": "5b9c2a77b6393d0001eb45fd",
            "name": {
              "first": "Demo",
              "last": "User"
            },
            "email": {
              "address": "demouser@gmail.com",
              "added": "2022-09-14T21:39:03.096Z",
              "verified": true
            },
            "events": {
              "last_login": "2020-03-18T19:28:15.14Z"
            }
          }
        }
      }
    }
  }
}