diff --git a/dist/ial.yml b/dist/ial.yml new file mode 100644 index 00000000..6928ee91 --- /dev/null +++ b/dist/ial.yml @@ -0,0 +1,1081 @@ +openapi: 3.1.0 +info: + license: + name: Apache-2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + version: 1.0.0 + title: Cycle Infrastructure Abstraction Layer + contact: + email: support@cycle.io + description: | + Cycle's Infrastructure Abstract Layer (IAL) API. Endpoints listed here should be implemented by the customer, and Cycle will call the various endpoints over the lifecycle of provisioning and decommissioning servers. + For more information, check out the official [Infrastructure Abstraction Layer Documentation](https://cycle.io/docs/platform/infrastructure-abstraction-layer). + + For a Go implementation of the types, see the repo available here: https://github.com/cycleplatform/integrations + x-logo: + url: https://static.cycle.io/icons/logo/logo-white.svg +servers: + - description: Cycle Infrastructure Abstraction Layer + url: https://api.cycle.io +security: [] +paths: + /v1/auth/verify: + post: + operationId: verifyAuth + summary: Verify Auth + description: Cycle will utilize this endpoint to verify that user-specified credentials can properly authorize with the IAL integration. + tags: + - Auth + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: 'null' + responses: + '200': + description: Returns an object with a `valid` property. Should be true if the authorization is successful. + content: + application/json: + schema: + type: object + required: + - valid + properties: + valid: + type: boolean + /v1/infrastructure/provider/locations: + get: + operationId: listLocations + summary: List Locations + description: Cycle will utilize this call to learn which locations it is able to deploy servers to. + tags: + - Provider + responses: + '200': + description: Returns a list of available server locations for this IAL. + content: + application/json: + schema: + type: object + required: + - locations + - extra + properties: + locations: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/Location' + extra: + type: + - object + - 'null' + additionalProperties: {} + /v1/infrastructure/provider/server-models: + get: + operationId: listServerModels + summary: List Server Models + description: Cycle will use this endpoint to learn which server types / models it is able to deploy (and which locations those servers can be deployed to). + tags: + - Provider + responses: + '200': + description: Returns a list of available server models available via this IAL integration. + content: + application/json: + schema: + type: object + required: + - models + - extra + properties: + models: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/ServerModel' + extra: + type: + - object + - 'null' + additionalProperties: {} + /v1/location/configure: + post: + operationId: configureLocation + summary: Configure Location + description: Cycle will call this endpoint before every server provision to enable an IAL integration to make location-specific customizations prior to starting servers. For example, with Cycle's native integration with AWS, we utilize this call to configure subnets and VPCs. + tags: + - Location + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: object + description: A request to update or configure the settings for a specific location. + required: + - location_id + - version + - configuration_current + - cycle + properties: + location_id: + type: string + description: The unique identifier of the location to be configured. + version: + type: string + description: The current version of the configuration being used at the location. + configuration_current: + type: object + description: Details of the current configuration settings for the location. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleLocationMeta' + responses: + '200': + description: Returns the updated location configuration. + content: + application/json: + schema: + type: object + description: The response provided after a request to configure a location, indicating whether the configuration was successful, and including details of the latest configuration. + required: + - configured + - configuration_latest + properties: + configured: + type: boolean + description: Indicates whether the location was successfully configured. + version: + type: + - string + - 'null' + description: The version of the configuration that was applied. This field can be null if the version is not applicable or not provided. + configuration_latest: + type: object + description: Details of the latest configuration settings for the location. + additionalProperties: true + /v1/infrastructure/server/provision: + post: + operationId: provisionServer + summary: Provision Server + description: Cycle will utilize this endpoint to start the provision of a server. + tags: + - Server + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: object + description: Properties for initiating a server provision. + required: + - hostname + - model_id + - location_id + - model_features + - location_configuration + - cycle + properties: + hostname: + type: string + description: The hostname for the server being provisioned. + model_id: + type: string + description: The ID of the server model to provision. + location_id: + type: string + description: The ID of the location where the server is to be provisioned. + zone_id: + type: + - string + - 'null' + description: The ID of the specific zone within the location for server provisioning. + model_features: + $ref: '#/components/schemas/SpecFeatures' + description: The features associated with the server model being provisioned. + provision_options: + type: object + description: Extra provisioning options specified from the platform. + additionalProperties: true + location_configuration: + type: object + description: Configuration details specific to the server's location. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleServerMeta' + responses: + '200': + description: Returns details about the server being provisioned. + content: + application/json: + schema: + type: object + description: The response received by Cycle after provisioning a server, including the unique server ID at the provider and any additional information. + required: + - server_id + properties: + server_id: + type: string + description: The unique identifier of the server at the provider. + extra: + type: object + description: A map containing additional, unspecified information related to the server provisioning. This allows for a flexible structure to include any extra data that doesn't fit into the standard response fields. + additionalProperties: true + /v1/infrastructure/server/provision-status: + get: + operationId: getProvisionServerStatus + summary: Get Provision Server Status + description: Cycle will use this endpoint to track the status of a provision and, when complete, authorize a server to pull CycleOS via IPXE. + tags: + - Server + responses: + '200': + description: Returns the status of a server provisioning request, including server ID, provisioning status, authentication details, and any additional extra information. + content: + application/json: + schema: + type: object + required: + - server_id + - provisioned + - auth + properties: + server_id: + type: string + description: The unique identifier of the server at the provider. + provisioned: + type: boolean + description: Indicates whether the server has been successfully provisioned. + auth: + type: object + description: Authentication details for the provisioned server. + properties: + uuid: + type: + - string + - 'null' + description: The UUID associated with the server for authentication purposes. Null if not yet assigned or applicable. + initial_ips: + type: + - array + - 'null' + items: + type: string + description: List of initial IP addresses assigned to the server. + mac_addr: + type: + - string + - 'null' + description: The MAC address of the server's primary network interface. Null if not yet assigned or applicable. + extra: + type: object + description: A map containing additional, unspecified information related to the server provisioning. This allows for flexible inclusion of any extra data outside the standard response fields. + additionalProperties: true + /v1/infrastructure/server/decommission: + post: + operationId: decommissionServer + summary: Decommission Server + description: Cycle will begin a decommission once a user initiates a 'delete' within the portal / API. This call will only occur after a server no longer has any IPs or instances assigned to it. + tags: + - Server + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: object + description: Represents a request to decommission a server, including server identification details, location, and any extra information required by the provider or for internal processes. + required: + - server_id + - hostname + - model_id + - location_id + - cycle + properties: + server_id: + type: string + description: The unique identifier of the server at the provider. + hostname: + type: string + description: The hostname of the server. + model_id: + type: string + description: The ID of the server model. + location_id: + type: string + description: The ID of the location where the server is deployedg. + zone_id: + type: + - string + - 'null' + description: The ID of the specific zone within the location, if applicable. + extra: + type: object + description: Additional, unspecified information associated with the server that might be relevant for the decommissioning process. This is an open map to accommodate various types of values. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleServerMeta' + responses: + '200': + description: Returns a boolean of the success of the decommission. + content: + application/json: + schema: + type: boolean + description: Will be true if the decommission is successful. + /v1/infrastructure/server/restart: + post: + operationId: restartServer + summary: Restart Server + description: Cycle will call this endpoint whenever a request has been made via the platform to restart a server. + tags: + - Server + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: object + description: Describes a request to restart a server. + required: + - server_id + - hostname + - model_id + - location_id + - cycle + properties: + server_id: + type: string + description: The unique identifier of the server at the provider. + hostname: + type: string + description: The hostname of the server. + model_id: + type: string + description: The model ID of the server. + location_id: + type: string + description: The ID of the location where the server is stationed, pertinent to the restart operation. + zone_id: + type: + - string + - 'null' + description: The zone ID within the location, if applicable. This field is optional and may be necessary for specific restart procedures. + extra: + type: object + description: Additional information associated with the server that might be required for the restart process. This allows for a flexible structure to include any extraneous data not covered by standard fields. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleServerMeta' + responses: + '200': + description: Returns a boolean of the success of the restart. + content: + application/json: + schema: + type: boolean + description: Will be true if the restart is successful. + /v1/infrastructure/ip/allocate: + post: + operationId: allocateIP + summary: Allocate IP Address + description: Cycle will call this endpoint to allocate an IP address. Generally this is done when a new load balancer is created (during environment create, or scaling up). + tags: + - IP + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - request + properties: + auth: + $ref: '#/components/schemas/Auth' + request: + type: object + description: Represents a request to allocate an IP address, detailing the kind of IP, relevant server and location identifiers, and configuration details. + required: + - kind + - server_id + - location_id + - location_configuration + - cycle + properties: + kind: + $ref: '#/components/schemas/IPKind' + server_id: + type: string + description: The unique identifier of the server for which the IP is being allocated. + location_id: + type: string + description: The identifier of the location where the server is situated and where the IP allocation is requested. + zone_id: + type: + - string + - 'null' + description: The identifier of the zone within the location, if applicable. This field is optional and can be null. + location_configuration: + type: object + description: Configuration details specific to the location, relevant to the IP allocation process. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleIPMeta' + responses: + '200': + description: Returns information about the allocated IP address. + content: + application/json: + schema: + type: object + required: + - ip_id + - ip_assignment_id + - cidr + - gateway + - netmask + - network + properties: + ip_id: + type: string + description: The unique identifier of the IP at the provider. + ip_assignment_id: + type: string + description: The unique identifier of the IP assignment at the provider. + cidr: + type: string + description: The CIDR notation of the allocated IP address. + gateway: + type: string + description: The gateway address for the allocated IP. + netmask: + type: string + description: The netmask associated with the allocated IP address. + network: + type: string + description: The network segment to which the allocated IP belongs. + nat_private_ip: + type: + - string + - 'null' + description: The private IP address for NAT (Network Address Translation), if applicable. + /v1/infrastructure/ip/release: + post: + operationId: releaseIP + summary: Release IP Address + description: When an IP is no longer needed, Cycle will release it using this API endpoint. + tags: + - IP + requestBody: + required: true + content: + application/json: + schema: + type: object + description: Represents a request to release an allocated IP address back to the provider, including detailed information about the IP and its assignment. + required: + - kind + - ip_id + - ip_assignment_id + - cidr + - server_id + - location_id + - location_configuration + - cycle + properties: + kind: + $ref: '#/components/schemas/IPKind' + ip_id: + type: string + description: The unique identifier of the IP at the provider. + ip_assignment_id: + type: string + description: The unique identifier of the IP assignment at the provider. + cidr: + type: string + description: The CIDR notation of the IP address being released. + nat_private_ip: + type: + - string + - 'null' + description: The private IP address used for NAT (Network Address Translation), if applicable. + zone_id: + type: + - string + - 'null' + description: The identifier of the zone within the location, if applicable. + server_id: + type: string + description: The unique identifier of the server associated with the IP. + location_id: + type: string + description: The identifier of the location where the IP was used. + location_configuration: + type: object + description: Configuration details specific to the location from which the IP is being released. + additionalProperties: true + cycle: + $ref: '#/components/schemas/CycleIPMeta' + responses: + '200': + description: Returns a boolean of the success of the release. + content: + application/json: + schema: + type: boolean + description: Will be true if the release is successful. +components: + schemas: + Auth: + title: Auth + description: The authorization object configured as part of the IAL integration on Cycle. All of these fields are custom, and can be interpreted by your API in any way desired. + type: object + properties: + client_id: + type: string + subscription_id: + type: string + namespace: + type: string + region: + type: string + api_key: + type: string + secret: + type: string + config: + type: string + format: base64 + description: If a provider needs a far more complex config, sent via base64. + cycle: + type: object + description: Meta information sent from Cycle about the hub the IAL integration is configured for. + required: + - hub_name + - hub_id + properties: + hub_name: + type: string + hub_id: + type: string + Geographic: + title: Geographic + type: object + required: + - latitude + - longitude + - city + - state + - country + - region + properties: + latitude: + type: number + format: float + longitude: + type: number + format: float + city: + type: string + state: + type: string + country: + type: string + region: + type: string + LocationProvider: + title: LocationProvider + description: Provider details for a location. + type: object + required: + - location_id + - code + - availability_zones + properties: + location_id: + type: string + description: The primary ID of how Cycle references this location + code: + type: string + availability_zones: + type: + - array + - 'null' + items: + type: string + Features: + title: Features + description: Features supported by a location. + type: object + required: + - available + - supported + properties: + available: + type: + - array + - 'null' + items: + type: string + supported: + type: + - array + - 'null' + items: + type: string + Location: + title: Location + description: A location offered by this IAL integration where servers can be deployed. + type: object + required: + - name + properties: + name: + type: string + description: The name of the location. + geographic: + oneOf: + - $ref: '#/components/schemas/Geographic' + - type: 'null' + provider: + $ref: '#/components/schemas/LocationProvider' + features: + $ref: '#/components/schemas/Features' + annotations: + oneOf: + - type: object + additionalProperties: + type: string + - type: 'null' + compatible: + type: + - boolean + - 'null' + CPU: + title: CPU + description: Details about the CPU for a given server model. + type: object + required: + - count + - type + properties: + count: + type: integer + format: int64 + description: The total number of CPUs. + cores: + type: + - integer + - 'null' + format: int64 + description: The number of cores per CPU. + threads: + type: + - integer + - 'null' + format: int64 + description: The number of threads per core. + type: + type: string + description: The type of the CPU. + shared: + type: + - boolean + - 'null' + description: Indicates if the CPU is shared among multiple tenants. + extra: + type: + - object + - 'null' + additionalProperties: + type: string + description: Extra information about the CPU. + GPU: + title: GPU + type: object + description: Describes an available GPU on a server model. + required: + - count + - type + properties: + count: + type: integer + format: int64 + description: The total number of GPUs. + cores: + type: + - integer + - 'null' + format: int64 + description: The number of cores per GPU, optional. + vram_gb: + type: + - integer + - 'null' + format: int64 + description: The amount of VRAM in GB per GPU, optional. + type: + type: string + description: The type of the GPU. + shared: + type: + - boolean + - 'null' + description: Indicates if the GPU is shared among multiple tenants, optional. + extra: + type: + - object + - 'null' + additionalProperties: + type: string + description: Extra information about the GPU, optional. + Memory: + title: Memory + type: object + required: + - size_gb + - type + properties: + size_gb: + type: integer + format: int64 + description: The size of the memory in gigabytes. + type: + type: string + description: The type of memory. + extra: + type: + - object + - 'null' + additionalProperties: + type: string + description: Extra information about the memory, optional. + Storage: + title: Storage + type: object + description: Represents a storage device or system, detailing its capacity, type, and additional metadata. + required: + - count + - size_gb + - type + properties: + count: + type: integer + format: int64 + description: The total number of storage devices. + size_gb: + type: integer + format: int64 + description: The storage capacity of each device in gigabytes. + type: + type: string + description: The type of storage, such as SSD or HDD. + extra: + type: + - object + - 'null' + additionalProperties: + type: string + description: Extra, optional information about the storage, allowing for additional, unspecified properties. + NIC: + title: NIC + type: object + description: Describes the properties of a Network Interface Card (NIC), including its scope, type, and throughput capabilities. + required: + - scope + - type + - throughput + properties: + scope: + type: string + description: Defines the operational scope of the NIC, such as 'local' or 'global'. + type: + type: string + throughput: + type: string + description: The maximum data transfer rate of the NIC, typically measured in Gbps (Gigabits per second). + SpecFeatures: + title: SpecFeatures + type: object + description: Details specific features available for the system, including RAID configuration and provider-specific features. + properties: + raid: + type: + - string + - 'null' + description: Specifies the RAID (Redundant Array of Independent Disks) configuration, if any. + hypervisor: + description: Indicates if the model supports virtual machines. + type: + - boolean + - 'null' + extra: + description: Provider specific features, allowing for additional, unspecified properties. This is an open map for any key-value pairs, accommodating various types of values. + oneOf: + - type: object + additionalProperties: true + - type: 'null' + Specs: + title: Specs + description: Detailed specs for a server model (CPU, RAM, etc.) + type: object + required: + - cpu + - memory + - features + properties: + cpu: + $ref: '#/components/schemas/CPU' + gpu: + oneOf: + - $ref: '#/components/schemas/GPU' + - type: 'null' + memory: + $ref: '#/components/schemas/Memory' + storage: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/Storage' + network: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/NIC' + description: A list of Network Interface Card (NIC) specifications. + features: + $ref: '#/components/schemas/SpecFeatures' + description: The set of additional features. + ServerModelProvider: + title: ServerModelProvider + type: object + description: Identifies the provider details, including the category, class, model ID, parent model ID, available locations, availability zones, and stock for a server, plan, or model. + required: + - name + - category + - model_id + properties: + name: + type: string + description: The name of the server model. + category: + type: string + description: The category of the server model. + class: + type: + - string + - 'null' + description: The class of the provider's server model, optional. + model_id: + type: string + description: The primary ID used to reference this server model. + parent_model_id: + type: + - string + - 'null' + description: The ID of the parent server model, if this model is derived from another. + locations: + type: + - array + - 'null' + items: + type: string + description: A list of locations where this server model is available. + availability_zones: + description: Details the availability zones where the server model is offered, keyed by location. + oneOf: + - type: object + additionalProperties: + type: array + items: + type: string + - type: 'null' + stock: + description: Stock information for the server model, keyed by location. + oneOf: + - type: object + additionalProperties: + type: object + required: + - quantity + - sync + properties: + quantity: + type: integer + description: The available quantity of stock at this location. + sync: + type: string + format: date-time + description: The time at which stock was last synced. + - type: 'null' + Pricing: + title: Pricing + type: object + description: Details the pricing structure for a service or product, specifying costs on an hourly and monthly basis. Prices are represented in mils (1/1000th of a dollar), allowing for precise cost specification. + required: + - hourly + - monthly + properties: + hourly: + type: integer + description: The cost per hour in mils. + monthly: + type: integer + description: The cost per month in mils. + ServerModel: + title: ProviderServerModel + type: object + description: Represents a server model, detailing its name, drivers, description, specifications, provider, pricing, and compatibility. + required: + - name + - description + - specs + - provider + - pricing + properties: + name: + type: string + description: The name of the server model. + drivers: + type: + - array + - 'null' + items: + type: string + description: A list of drivers supported by the server model. This field can be null to represent cases where drivers are not specified or applicable. + description: + type: string + description: A detailed description of the server model. + specs: + $ref: '#/components/schemas/Specs' + description: The specifications of the server model, including CPU, GPU, memory, and other components. + provider: + $ref: '#/components/schemas/ServerModelProvider' + description: The provider of the server model. + pricing: + $ref: '#/components/schemas/Pricing' + description: Pricing information for the server model. + compatible: + type: + - boolean + - 'null' + description: Indicates whether the server model is compatible with a specific environment or requirement. This field can be null to represent cases where compatibility has not been determined. + CycleLocationMeta: + title: CycleServerMeta + type: object + description: Metadata about a location, provided by Cycle. + required: + - location_id + properties: + location_id: + type: string + format: uuid + description: The unique identifier of the location at Cycle. + CycleServerMeta: + title: CycleServerMeta + type: object + description: Metadata about a server, provided by Cycle. + required: + - server_id + - model_class + - model_category + - model_id + - location_id + properties: + server_id: + type: string + format: uuid + description: The unique identifier of the server at Cycle. + model_class: + type: string + description: The class of the server at Cycle, + model_category: + type: string + description: The category of the server at Cycle. + model_id: + type: string + format: uuid + description: The unique identifier of the model at Cycle. + location_id: + type: string + format: uuid + description: The unique identifier of the location at Cycle. + IPKind: + title: IPKind + type: string + description: The kind (IPv4 or IPv6) of an IP. + enum: + - ipv4 + - ipv6 + CycleIPMeta: + title: CycleIPMeta + type: object + description: Metadata associated with an IP within Cycle. + required: + - server_id + - server_model_class + - server_model_category + - location_id + properties: + pool_id: + type: + - string + - 'null' + format: uuid + description: The unique identifier of the IP pool. + server_id: + type: string + format: uuid + description: The unique identifier of the server associated with the IP. + server_model_class: + type: string + description: The class of the server, categorizing the server based on its specifications or purpose at Cycle. + server_model_category: + type: string + description: The category of the server, providing a broader classification than the class at Cycle. + location_id: + type: string + format: uuid + description: The unique identifier of the location associated with the server. diff --git a/dist/internal.yml b/dist/internal.yml new file mode 100644 index 00000000..e2dfe078 --- /dev/null +++ b/dist/internal.yml @@ -0,0 +1,8709 @@ +openapi: 3.1.0 +info: + license: + name: Apache-2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + title: Cycle Internal API + description: | + Inside every container running on Cycle, there is a Unix socket mounted at *`/var/run/cycle/api/api.sock`*. You can send HTTP requests over this socket to access information about the local environment, access secrets, and much more. + The way this internal API functions is very similar to how Cycle's main API works, though the purpose is different. The internal API is primarily used by instances to learn about their environment, and dynamically update as deployments change. In the future, we expect you'll be able to use the internal API to register service containers and much more. + The internal API returns identical JSON responses to the main API. There is also a websocket based API that you can tune into for streaming platform updates. + version: 1.0.0 + contact: + email: support@cycle.io + x-logo: + url: https://static.cycle.io/icons/logo/logo-white.svg +servers: + - description: Cycle Internal API + url: http://localhost + x-unix-socket: + description: Unix socket path for internal API + url: /var/run/cycle/api/api.sock +security: + - tokenAuth: [] +paths: + /v1/environment: + get: + operationId: getEnvironment + summary: Get Environment + description: | + Gets the Environment that this instance is a part of. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns an Environment. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Environment' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/containers: + get: + operationId: getEnvironmentContainers + summary: List Environment Containers + description: | + Lists all Containers that are part of the same Environment as this Instance. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a collection of container resources. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Container' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/instances: + get: + operationId: getEnvironmentInstances + summary: List Environment Instances + description: | + Lists all instances present in this instance's environment. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + - Instances + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a list of instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/ips: + get: + operationId: getEnvironmentIPs + summary: List Environment IPs + description: | + Lists the IPs associated with this Instance's Environment. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a list of detailed IP objects. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Ip' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/services: + get: + operationId: getEnvironmentServices + summary: List Environment Services + description: | + Lists the services containers/instances that are in the same environment as this instance. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a list of environment services (a combination of container and instance details). + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + properties: + discovery: + $ref: '#/components/schemas/ServiceContainer' + vpn: + $ref: '#/components/schemas/ServiceContainer' + loadbalancer: + $ref: '#/components/schemas/ServiceContainer' + scheduler: + $ref: '#/components/schemas/ServiceContainer' + gateway: + $ref: '#/components/schemas/ServiceContainer' + additionalProperties: + $ref: '#/components/schemas/ServiceContainer' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/virtual-machines: + get: + operationId: getEnvironmentVirtualMachines + summary: Get Environment Virtual Machines + description: | + Returns a list of virtual machines that are in the same environment as this instance. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a list of virtual machines. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/VirtualMachine' + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/services/lb/telemetry/snapshots: + post: + operationId: submitLoadBalancerTelemetry + summary: Submit Environment Load Balancer Telemetry + description: | + Submit load balancer telemetry data. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Environments + x-cycle-scopes: + - environment + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: + $ref: '#/components/schemas/LoadBalancerTelemetrySnapshot' + responses: + '200': + description: Returns a list of Instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: boolean + default: + $ref: '#/components/responses/DefaultError' + /v1/environment/scoped-variables: + get: + operationId: getEnvironmentScopedVariables + summary: Get Environment Scoped Variables + description: | + Gets the scoped variables that are accessible to this instance via internal API. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Scoped Variables + x-cycle-scopes: + - environment + parameters: [] + responses: + '200': + description: Returns a map of variable values, keyed by their identifier. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + additionalProperties: + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/hub: + get: + operationId: getHub + summary: Get Hub + description: | + Gets the hub that this instance is a member of. + + Does not require a scope + tags: + - Hubs + parameters: [] + x-cycle-scopes: + - none + responses: + '200': + description: Returns a hub. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/PublicHub' + default: + $ref: '#/components/responses/DefaultError' + /v1/hub/integrations: + get: + operationId: getHubIntegration + summary: Get Hub Integration + description: | + Gets an integration based on a provided identifier or vendor query parameter. At least one of these must be provided. + + Only internal Cycle services can access this endpoint at this time. + tags: + - Hubs + x-cycle-scopes: + - none + parameters: + - name: identifier + in: query + required: false + description: An integration identifier. + schema: + type: string + - name: vendor + in: query + required: false + description: An integration vendor. + schema: + type: string + responses: + '200': + description: Returns a hub integration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Integration' + default: + $ref: '#/components/responses/DefaultError' + /v1/server: + get: + operationId: getServer + tags: + - Servers + parameters: [] + summary: Get Server + description: | + Gets the server this instance is running on. + + Requires the `server` scope to be set on the container runtime config. + x-cycle-scopes: + - server + responses: + '200': + description: Returns a server. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Server' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/instances: + get: + operationId: getServerInstances + summary: Get Server Instances + description: | + Gets a list of instances that are on the same server as this instance. + + Requires the `server` scope to be set on the container runtime config. + tags: + - Servers + - Instances + parameters: [] + x-cycle-scopes: + - server + responses: + '200': + description: Returns a list of instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/external-volumes: + get: + operationId: getServerExternalVolumes + summary: List Server External Volumes + description: | + Lists all external volumes connected to this server. + + Requires the `server` scope to be set on the container runtime config. + tags: + - Servers + parameters: [] + x-cycle-scopes: + - server + responses: + '200': + description: Returns a list of external volumes. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ExternalVolume' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/containers: + get: + operationId: getServerContainers + tags: + - Servers + - Containers + parameters: [] + x-cycle-scopes: + - server + summary: List Server Containers + description: | + Lists all containers present on the same server as this instance. + + Requires the `server` scope to be set on the container runtime config. + responses: + '200': + description: Returns a list of containers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Container' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/images: + get: + operationId: getServerImages + summary: List Server Images + description: | + Lists all images downloaded onto the server this instance is on. + + Requires the `server` scope to be set on the container runtime config. + tags: + - Servers + - Containers + parameters: [] + x-cycle-scopes: + - server + responses: + '200': + description: Returns a list of image details (id, time accessed). + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + required: + - id + - access_time + properties: + id: + $ref: '#/components/schemas/ID' + access_time: + $ref: '#/components/schemas/DateTime' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/images/download: + post: + operationId: downloadImage + summary: Download Image + description: | + Downloads the specified image to the server. + + Requires the `server` scope to be set on the container runtime config. + tags: + - Servers + - Images + parameters: [] + x-cycle-scopes: + - server + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - image_id + properties: + image_id: + $ref: '#/components/schemas/ID' + responses: + '200': + description: Returns the details of the downloaded image. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + required: + - id + - access_time + properties: + id: + $ref: '#/components/schemas/ID' + access_time: + $ref: '#/components/schemas/DateTime' + default: + $ref: '#/components/responses/DefaultError' + /v1/server/power/poweroff: + post: + operationId: poweroffServer + summary: Power Off Server + description: | + Initiates a graceful poweroff on the host server this instance is running on. + + Does not require a scope, but the container must have `config.runtime.host.power_management` set to true to utilize this endpoint. + tags: + - Servers + parameters: [] + x-cycle-scopes: + - none + responses: + '200': + description: Returns a generic success result. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: boolean + default: + $ref: '#/components/responses/DefaultError' + /v1/server/power/reboot: + post: + operationId: rebootServer + summary: Reboot Server + description: | + Initiates a graceful reboot on the host server this instance is running on. + + Does not require a scope, but the container must have `config.runtime.host.power_management` set to true to utilize this endpoint. + tags: + - Servers + parameters: [] + x-cycle-scopes: + - none + responses: + '200': + description: Returns a generic success result. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: boolean + default: + $ref: '#/components/responses/DefaultError' + /v1/container: + get: + operationId: getContainer + summary: Get Container + description: | + Gets a container. By default will grab the container of this instance, but a `container-id`` parameter can be passed to grab any other container in the same environment. + + Requires the `self` scope to be set on the container runtime config. + tags: + - Containers + x-cycle-scopes: + - self + parameters: + - name: container-id + in: query + required: false + description: Specify which container to fetch. If not provided, will use the container of the current instance. + schema: + type: string + responses: + '200': + description: Returns a container. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Container' + default: + $ref: '#/components/responses/DefaultError' + /v1/container/instances: + get: + operationId: getContainerInstances + summary: Get Container Instances + description: | + Gets the instances of a container. By default will grab the instances of the same container, but a `container-id`` parameter can be passed to grab any other container instances in the same environment. + + Requires the `self` scope to be set on the container runtime config. + tags: + - Containers + - Instances + x-cycle-scopes: + - self + parameters: + - name: container-id + in: query + required: false + description: Specify which container to fetch instances of. If not provided, will use the container of the current instance. + schema: + type: string + responses: + '200': + description: Returns a list of instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/certificates: + get: + operationId: getContainerCertificates + summary: List Container Certificates + description: | + Get the TLS certificates associated with the domains pointed at this container. + + Requires the `self` scope to be set on the container runtime config. + tags: + - Containers + x-cycle-scopes: + - self + parameters: + - name: container-id + in: query + required: false + description: Specify which container to get certificates for. If not provided, will use the container of the current instance. + schema: + type: string + responses: + '200': + description: Returns a list of TLS certificates. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Certificate' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/domains: + get: + operationId: getContainerDomains + summary: List Container Domains + description: | + Get the domains pointed at a container. + + Requires the `self` scope to be set on the container runtime config. + tags: + - Containers + x-cycle-scopes: + - self + parameters: + - name: container-id + in: query + required: false + description: Specify which container to get domains for. If not provided, will use the container of the current instance. + schema: + type: string + responses: + '200': + description: Returns a list of domains. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + description: Any associated Linked Records for this container, and their fully-qualified domain name (fqdn). + required: + - fqdn + properties: + fqdn: + type: string + description: The fully qualified domain name. + record: + $ref: '#/components/schemas/DnsRecord' + default: + $ref: '#/components/responses/DefaultError' + /v1/ha/election/checkin: + post: + operationId: highAvailabilityCheckin + summary: High Availability Checkin + description: | + Hit this endpoint every 30 seconds to check in and have the platform select and maintain a primary instance. + Every instance you wish to be considered for a primary should hit this endpoint roughly every 30 seconds. The platform will choose one instance as the primary, and it will continue to be the primary until it stops checking in. If a primary stops checking in, a secondary will be selected to be promoted to primary. + + Does not require a scope, but `config.deploy.ha_elections` must be enabled on this container to access this endpoint. + tags: + - High Availability + x-cycle-scopes: + - none + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - electable + - priority + properties: + electable: + type: boolean + description: Whether this instance wishes to be considered for election as the primary. + priority: + type: integer + format: int32 + description: The election priority for this instance. Higher priority means more likely to be elected primary. + responses: + '200': + description: Returns the result of the high availability check-in. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - time + - primary_instance_id + properties: + time: + description: The time the platform recorded this check-in. + $ref: '#/components/schemas/DateTime' + primary_instance_id: + description: The ID of the instance currently elected as the primary. Null when no primary has been elected yet. + oneOf: + - $ref: '#/components/schemas/ID' + - type: 'null' + default: + $ref: '#/components/responses/DefaultError' + /v1/monitoring/metrics: + post: + operationId: postMetric + summary: Post Metric + description: | + Post data to Cycle's monitoring system. + + Does not require a scope. + tags: + - Monitoring + x-cycle-scopes: + - none + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Metric' + responses: + '200': + description: Returns true on success. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: boolean + enum: + - true + default: + $ref: '#/components/responses/DefaultError' + /v1/monitoring/events: + post: + operationId: postEvent + summary: Post Event + description: | + Post a custom event to Cycle's monitoring system. + + Does not require a scope. + tags: + - Monitoring + x-cycle-scopes: + - none + parameters: [] + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Event' + responses: + '200': + description: Returns true on success. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: boolean + enum: + - true + default: + $ref: '#/components/responses/DefaultError' + /v1/sdn/networks: + get: + operationId: getNetworks + summary: List Networks + description: | + Lists all networks attached to this instance. + + Requires the `networks` scope to be set on the container runtime config. + tags: + - SDN + parameters: [] + x-cycle-scopes: + - networks + responses: + '200': + description: Returns a list of networks. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Network' + default: + $ref: '#/components/responses/DefaultError' + /v1/sdn/networks/instances: + get: + operationId: getNetworkInstances + summary: List Network Instances + description: | + Lists all instances present in this instance's SDN networks. + + Requires the `networks` scope to be set on the container runtime config. + tags: + - SDN + - Instances + parameters: [] + x-cycle-scopes: + - networks + responses: + '200': + description: Returns a list of instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + default: + $ref: '#/components/responses/DefaultError' + /v1/sdn/networks/environments: + get: + operationId: getNetworkEnvironments + summary: List Network Environments + description: | + Lists all environments present in this instance's SDN networks. + + Requires the `networks` scope to be set on the container runtime config. + tags: + - SDN + - Environments + parameters: [] + x-cycle-scopes: + - networks + responses: + '200': + description: Returns a list of environments. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Environment' + default: + $ref: '#/components/responses/DefaultError' + /v1/virtual-machine: + get: + operationId: getVirtualMachine + summary: Get Virtual Machine + description: | + Returns a specified virtual machine. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Virtual Machines + x-cycle-scopes: + - environment + parameters: + - name: virtual-machine-id + in: query + required: true + description: Specify which virtual machine to fetch. + schema: + type: string + responses: + '200': + description: Returns a virtual machine. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VirtualMachine' + default: + $ref: '#/components/responses/DefaultError' + /v1/virtual-machine/domains: + get: + operationId: getVirtualMachineDomains + summary: Get Virtual Machine Domains + description: | + Returns the domains associated with the specified virtual machine. + + Requires the `environment` scope to be set on the container runtime config. + tags: + - Virtual Machines + x-cycle-scopes: + - environment + parameters: + - name: virtual-machine-id + in: query + required: true + description: Specify which virtual machine to fetch domains for. + schema: + type: string + responses: + '200': + description: Returns a list of virtual machine domains. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + required: + - fqdn + properties: + fqdn: + type: string + record: + anyOf: + - $ref: '#/components/schemas/DnsRecord' + default: + $ref: '#/components/responses/DefaultError' + /v1/object-cache: + get: + operationId: getObjectCache + summary: Get Object Cache + description: | + Returns an object saved to the internal object cache. + + Requires the `server` scope to be set on the container runtime config if using the `global` cache. + Requires the `environment` scope to be set on the container runtime config if using the `environment` cache. + Requires the `self` scope to be set on the container runtime config if using the `container` or `instance` cache. + tags: + - Object Cache + x-cycle-scopes: + - server + - environment + - self + parameters: + - name: scope + in: query + required: true + description: Specify the object scope. + schema: + type: string + enum: + - global + - environment + - container + - instance + - name: key + in: query + required: true + description: Specify the object key. + schema: + type: string + responses: + '200': + description: Returns a saved object cache item. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ObjectCacheSave' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: postObjectCache + summary: Post Object Cache + description: | + Save an item to the internal API object cache. + + Requires the `server` scope to be set on the container runtime config if using the `global` cache. + Requires the `environment` scope to be set on the container runtime config if using the `environment` cache. + Requires the `self` scope to be set on the container runtime config if using the `container` or `instance` cache. + tags: + - Object Cache + parameters: [] + x-cycle-scopes: + - server + - environment + - self + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ObjectCacheSave' + responses: + '200': + description: Returns true on success. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: 'null' + default: + $ref: '#/components/responses/DefaultError' +components: + securitySchemes: + tokenAuth: + name: X-CYCLE-TOKEN + in: header + type: apiKey + description: The authentication header for every request on the internal API. Take the value of the CYCLE_API_TOKEN environment variable present in the instance, and pass it as the value to this header to authenticate. + basicAuth: + type: http + scheme: basic + schemas: + Capability: + type: string + description: A capability that a user or API key that represents what an API key or a user can do. + enum: + - external-volumes-view + - external-volumes-manage + - api-keys-manage + - apionly-jobs-view + - apionly-notifications-listen + - autoscale-groups-manage + - autoscale-groups-view + - billing-credits-view + - billing-invoices-pay + - billing-invoices-view + - billing-methods-manage + - billing-services-manage + - billing-services-view + - containers-backups-manage + - containers-backups-view + - containers-console + - containers-deploy + - containers-instances-migrate + - containers-lock + - containers-ssh + - containers-manage + - containers-view + - containers-functions-trigger + - containers-volumes-manage + - containers-volumes-view + - dns-certs-view + - dns-manage + - dns-view + - environments-deployments-manage + - environments-manage + - environments-scopedvariables-manage + - environments-scopedvariables-view + - environments-services-manage + - environments-view + - environments-vpn + - environments-vpn-manage + - hubs-delete + - hubs-integrations-manage + - hubs-integrations-view + - hubs-invites-manage + - hubs-invites-send + - hubs-members-manage + - hubs-members-view + - hubs-roles-manage + - hubs-roles-view + - hubs-usage-view + - hubs-update + - hubs-auditlog-view + - images-manage + - images-sources-manage + - images-sources-view + - images-view + - ips-manage + - servers-console + - servers-decommission + - servers-login + - clusters-manage + - clusters-view + - servers-provision + - servers-manage + - servers-view + - monitor-manage + - monitor-view + - pipelines-manage + - pipelines-trigger + - pipelines-view + - sdn-networks-manage + - sdn-networks-view + - security-manage + - security-view + - stacks-builds-deploy + - stacks-builds-manage + - stacks-manage + - stacks-view + - virtual-machines-view + - virtual-machines-manage + - virtual-machines-deploy + - virtual-machines-console + - virtual-machines-lock + - virtual-machines-ssh-keys-manage + - virtual-machines-root-pw-view + - virtual-machines-root-pw-view-temp + Error: + title: Error + description: |- + The Cycle API uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate a request that failed due to input, and codes in the `5xx` range indicate an error on Cycle's part (rare). + There are two types of error response objects. Errors with authentication are formatted to follow the OAuth spec, while all other errors follow the same convention. If you're using one of our API Libraries, they will standardize OAuth errors to fit the general convention. + type: object + required: + - status, code, title + properties: + status: + type: integer + description: The HTTP response code. + enum: + - 400 + - 401 + - 403 + - 404 + - 409 + - 415 + - 422 + - 500 + - 501 + - 502 + - 503 + - 504 + code: + type: string + description: A Cycle standard error code. + enum: + - 400.invalid-syntax + - 401.auth-invalid + - 401.auth-expired + - 401.no-cookie + - 401.unauthorized-application + - 403.mismatch + - 403.wrong-hub + - 403.not-ready + - 403.expired + - 403.restricted-portal + - 403.permissions + - 403.invalid-ip + - 403.invalid-state + - 403.not-approved + - 403.not-allowed + - 403.platform-disabled + - 403.2fa-required + - 403.2fa-failed + - 403.new-application-capabilities + - 403.tier-restricted + - 404.hub + - 404.hub.invitation + - 404.hub.integration + - 404.hub.role + - 404.sdn.network + - 404.environment + - 404.environment.scoped-variable + - 404.hub.api-key + - 404.uri + - 404.provider + - 404.stack + - 404.community.thread + - 404.community.thread.reply + - 404.survey + - 404.survey-response + - 404.notification + - 404.stack-build + - 404.image + - 404.image.source + - 404.image.build-log + - 404.job + - 404.billing.order + - 404.billing.service + - 404.billing.credit + - 404.billing.invoice + - 404.billing.tier + - 404.billing.support + - 404.billing.payment-method + - 404.billing.promo-code + - 404.node + - 404.infrastructure.location + - 404.infrastructure.ips.pool + - 404.infrastructure.provider + - 404.infrastructure.server + - 404.infrastructure.cluster + - 404.infrastructure.autoscale.group + - 404.infrastructure.model + - 404.infrastructure.external-volume + - 404.monitoring.logs.analytics.rule + - 404.account + - 404.container + - 404.container.backup + - 404.vpn.account + - 404.instance + - 404.pipeline + - 404.pipeline.run + - 404.pipeline.key + - 404.dns.zone + - 404.dns.record + - 404.cluster + - 404.platform-build + - 404.cycleos-build + - 404.email-verification + - 404.hub.membership + - 404.announcement + - 404.ha-service.session + - 404.virtual-machine + - 404.virtual-machine.ssh-key + - 404.sales.lead + - 404.stack.build-log + - 409.duplicate-found + - 415.invalid-content-type + - 422.missing-argument + - 422.invalid-argument + - 422.invalid-input + - 422.max-exceeded + - 422.not-compatible + - 422.already-exists + - 429.rate-limiting + - 500.database + - 500.database-insert + - 500.database-update + - 500.database-remove + - 500.jobd + - 500.unknown + - 500.dev + - 500.email + - 503.not-ready + - 503.not-enabled + - 503.dependency-not-enabled + - 504.not-available + title: + type: string + description: The main text describing the error. + detail: + type: string + description: A more detailed description of the error. + source: + type: string + description: A [JSON pointer](https://tools.ietf.org/html/rfc6901/) describing the source of an error. + extra: + type: object + description: Additional entries on the error object to provide extra details. + properties: + capability: + description: If the error occured because of a lack of permission (403), this will list the specific capability that the Role/API Key is missing. + $ref: '#/components/schemas/Capability' + ErrorEnvelope: + title: ErrorEnvelope + type: object + description: An error response. + required: + - error + - data + properties: + error: + $ref: '#/components/schemas/Error' + data: + type: 'null' + ID: + title: ID + type: string + format: objectid + description: A 24 character hex string used to identify a unique resource. + examples: + - 651586fca6078e98982dbd90 + Identifier: + title: Identifier + type: string + description: | + A human-readable identifier used to refer to a resource, where using the official ID may be inconvenient. + The identifier is automatically tokenized from the name/relevant field of the resource if one is not provided. For example, a container named "My Container" will + have the identifier of `my-container` and is automatically created by the platform. + + The identifier does not have to be unique. + EnvironmentAbout: + title: EnvironmentAbout + type: object + description: Contains details regarding the environment. + required: + - description + - favorite + properties: + description: + type: string + description: A custom description for this environment. + favorite: + type: boolean + description: If true, this environment has been marked as a favorite. + CreatorScope: + title: CreatorScope + description: The creator scope is embedded in resource objects to describe who created them + type: object + required: + - id + - type + properties: + id: + $ref: '#/components/schemas/ID' + type: + type: string + enum: + - account + - environment + - platform + - platform-pipeline + - employee + - api-key + - visitor + HubID: + title: HubID + type: string + description: The unique ID of the Hub this resource was created in. + examples: + - 651586fca6078e98982dbd90 + DateTime: + title: DateTime + type: string + format: date-time + examples: + - '2021-01-30T08:30:00Z' + State: + title: State + description: Information regarding the current state of the resource. + type: object + required: + - changed + properties: + changed: + $ref: '#/components/schemas/DateTime' + error: + type: object + description: An error, if any, that has occurred for this resource. + properties: + message: + type: string + description: Details about the error that has occurred. + time: + description: The timestamp of when the error was encountered. + $ref: '#/components/schemas/DateTime' + EnvironmentState: + title: EnvironmentState + allOf: + - required: + - current + properties: + current: + description: The current state of the environment. + type: string + enum: + - new + - live + - cloning + - deleting + - deleted + - $ref: '#/components/schemas/State' + MonitoringTier: + title: MonitoringTier + type: string + description: The tier of monitoring, that determines the frequency that metrics are aggregated by the platform, on a per-environment basis. + enum: + - standard + - plus + - premium + - scale + LogFormat: + title: LogFormat + type: string + enum: + - ndjson-headers + - ndjson-raw + EnvironmentMonitoringConfig: + title: EnvironmentMonitoringConfig + type: object + description: The configuration for environment monitoring. + properties: + logs: + description: An object describing the log monitoring configuration for the environment. + oneOf: + - type: object + properties: + drain: + description: An object describing log drain configuration for the environment. + oneOf: + - type: object + required: + - url + - exclude_services + properties: + url: + description: The destination URL for the log drain. + type: string + format: + description: The format of the logs that will be sent to the drain URL. + $ref: '#/components/schemas/LogFormat' + exclude_services: + description: If enabled, service logs will not be included in log drain. + type: boolean + - type: 'null' + - type: 'null' + metrics: + description: An object describing the metrics monitoring configuration for the environment. + oneOf: + - type: object + properties: + endpoint: + description: | + Configuration options for pushing metrics externally. + For payload see webhook `environmentMetricsPush` + oneOf: + - type: object + required: + - url + properties: + url: + description: The destination URL for the metrics. + type: string + - type: 'null' + - type: 'null' + events: + description: An object describing the events monitoring configuration for the environment. + oneOf: + - type: object + properties: + endpoint: + description: | + Configuration options for pushing events externally. + For payload see webhook `environmentEventsPush` + oneOf: + - type: object + required: + - url + properties: + url: + description: The destination URL for events. + type: string + - type: 'null' + - type: 'null' + EnvironmentFeatures: + title: EnvironmentFeatures + type: object + description: An object representing specialized features configured for this environment. + required: + - legacy_networking + properties: + legacy_networking: + description: Whether or not legacy networking mode is enabled on this environment. + type: boolean + monitoring: + description: The level of monitoring to enable for this environment. There is a cost associated with higher levels of monitoring. + oneOf: + - type: object + required: + - tier + properties: + tier: + $ref: '#/components/schemas/MonitoringTier' + config: + $ref: '#/components/schemas/EnvironmentMonitoringConfig' + - type: 'null' + HaProxyConfigSet: + title: HAProxyConfigSet + type: object + required: + - frontend + - backend + properties: + frontend: + type: object + description: Settings that describe how incoming traffic to the load balancer is handled. + required: + - mode + - max_connections + - timeouts + properties: + mode: + type: string + description: |- + The type of traffic expected by the load balancer for this port. Can be either: + - tcp: Traffic is forwarded without any parsing or additional manipulation. + - http: Traffic is treated as web traffic. If a LINKED record is configured for a container exposing this port, the domain will be parsed and it will be forwarded to the proper container. This allows multiple services to run on port 80 in the same environment. + enum: + - tcp + - http + max_connections: + type: + - integer + - 'null' + description: The number of simultaneous connections that can be processed at a time. + timeouts: + type: + - object + - 'null' + description: Various options for handling timeouts when communicating with the client. + required: + - client_secs + - client_fin_ms + - http_keep_alive_ms + - http_request_ms + properties: + client_secs: + type: + - integer + - 'null' + description: The number of seconds the load balancer will wait for a response from a client before disconnecting. + client_fin_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will wait for a client to send it data when one direction is already closed. This is particularly useful to avoid keeping connections in a waiting state for too long when clients do not disconnect cleanly. + http_keep_alive_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will wait for a new HTTP request to start coming after a response was set. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-timeout%20http-request) for more information. (`http` mode only) + http_request_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will wait for a complete HTTP request. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-timeout%20http-request) for more information. (`http` mode only) + backend: + type: object + description: Settings related to how the load balancer routes connections to container instances. + required: + - balance + - timeouts + properties: + balance: + type: string + description: |- + How connections are balanced across your container instances. Can be one of the following: + - `roundrobin`: Each container instance is used in turns. + - `static-rr`: Each container instance is used in turns, but is faster than Round Robin at the expense of being less dynamic. + - `leastconn`: Routes traffic to the instance with the least number of active connections. + - `first`: Routes traffic to the first available instance. + - `source`: The same client IP always reaches the same container instance as long as no instance goes down or up. + enum: + - roundrobin + - static-rr + - leastconn + - first + - source + timeouts: + type: + - object + - 'null' + description: Various options for handling timeouts when communicating with a container instance behind the load balancer. + required: + - server_secs + - server_fin_ms + - connect_ms + - queue_ms + - tunnel_secs + properties: + server_secs: + type: + - integer + - 'null' + description: The number of seconds the load balancer will wait for a response from the container instance. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4.2-timeout%20server) for more information. + server_fin_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will wait for the server to send data when one direction is already closed. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4-timeout%20server-fin) for more information. + connect_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will wait for a successful connection to a container instance. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4-timeout%20connect) for more information. + queue_ms: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will hold connections in a queue when the maximum number of connections has been reached. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4-timeout%20queue) for more information. + tunnel_secs: + type: + - integer + - 'null' + description: The number of milliseconds the load balancer will allow for inactivity on a bidirectional tunnel. See the [HAProxy Docs](https://cbonte.github.io/haproxy-dconv/1.7/configuration.html#4-timeout%20tunnel) for more information. + HaProxyConfig: + title: HaProxyConfig + type: object + description: Describes settings that are passed to HAProxy within the load balancer. + required: + - default + - ports + properties: + default: + description: Settings that are applied to any port that is not overridden in the following ports section. + $ref: '#/components/schemas/HaProxyConfigSet' + ports: + description: An object that defines how HAProxy will act on a specific port. The key is a custom port, and the value is the same settings object found under `default` above. + type: object + additionalProperties: + $ref: '#/components/schemas/HaProxyConfigSet' + HaProxyLbType: + title: HaProxyLbType + type: object + required: + - type + - details + - ipv4 + - ipv6 + - performance + properties: + performance: + type: boolean + description: Enable / disable performance mode. If enabled, load balancer can use much more RAM and CPU. + ipv4: + type: boolean + description: Allow / disallow traffic to be routed via IPv4. + ipv6: + type: boolean + description: Allow / disallow traffic to be routed via IPv6. + type: + type: string + enum: + - haproxy + details: + anyOf: + - $ref: '#/components/schemas/HaProxyConfig' + - type: 'null' + WafConfig: + title: WafConfig + type: object + description: Additional configuration options for the web application firewall. + required: + - rules + properties: + rules: + type: array + items: + type: object + required: + - description + - skip + - type + - match + - conditions + properties: + description: + description: Some information about the rule. + type: string + skip: + description: A boolean that indicates if the rule should be active or skipped. + type: boolean + type: + description: | + A string that describes if the role should allow, deny, or block traffic based on the conditions. + - block = http 403 + - deny = connection disconnect + type: string + enum: + - allow + - deny + - block + expires: + description: The expiration date of the WAF config, if present. + oneOf: + - $ref: '#/components/schemas/DateTime' + - type: 'null' + match: + description: A string that describes if both attributes need to be true (match all) or if only one of the conditions needs to be true (match any). + type: string + enum: + - any + - all + - '' + sample: + description: | + Percentage range from 0 to 100 + Sample = 100 => the rule is applied to 100% of requests + Sample = 0 => the rule applies to 0% of requests + type: + - integer + - 'null' + response: + description: Response configuration for when the rule is triggered. + oneOf: + - type: object + properties: + http_code: + description: The HTTP code that will be sent back to the requester on rule match. + type: integer + - type: 'null' + conditions: + description: An array of the specific conditions for the rule. + type: array + items: + type: object + required: + - type + - operator + - value + properties: + key: + description: | + An optional key used to target a specific attribute within the condition type. + For example, when using `http-header-match`, the key would be the header name (e.g., `X-Forwarded-For`). + type: + - string + - 'null' + value: + description: The value corresponding to the condition type. + examples: + - 0.0.0.0/0 + type: string + regex: + description: | + When `true`, the `value` field is interpreted as a regular expression pattern + rather than a literal string. Allows for advanced pattern matching on condition values. + type: boolean + default: false + type: + description: A string that describes the match type for the condition. + type: string + enum: + - ip-match + - geo-match + - http-url-match + - http-method-match + - http-header-match + - http-body-match + operator: + type: string + description: | + Defines the comparison operator used to evaluate the rule condition + against the provided `value`. + enum: + - '==' + - '!=' + - '*=' + - '!*=' + - ^= + - '!^=' + - '>' + - < + - '>=' + - <= + x-enum-descriptions: + - Equal to — the condition value must exactly match. + - Not equal to — the condition value must differ. + - Contains — the request value must contain the provided substring. + - Does not contain — the request value must not contain the substring. + - Starts with — the request value must begin with the provided prefix. + - Does not start with — the request value must not begin with the prefix. + - Greater than — numeric comparison. + - Less than — numeric comparison. + - Greater than or equal — numeric comparison. + - Less than or equal — numeric comparison. + Duration: + title: Duration + type: string + description: A string signifying a duration of time. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d", "w", "y". + examples: + - 72h45m2s + TcpTransportConfig: + title: TcpTransportConfig + description: Additional configuration options for the TCP transport mode. + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - tcp + details: + type: object + required: + - connections + - telemetry + properties: + connections: + type: object + additionalProperties: {} + telemetry: + type: object + description: Configuration options for how telemetry is handled on the load balancer. + additionalProperties: {} + HttpTransportConfig: + title: HttpTransportConfig + description: Additional configuration options for the HTTP transport mode. + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - http + details: + type: object + required: + - connections + - telemetry + properties: + connections: + type: object + required: + - max_idle_conns_per_connection + description: Defines extra configuration options connections to the load balancer + properties: + max_idle_conns_per_connection: + type: + - integer + - 'null' + description: Maximum number of simultaneous connections (via http/2) per connection. + telemetry: + type: object + description: Configuration options for how telemetry is handled. + properties: + max_trackable_urls: + description: Determines how many URLs the load balancer will track at one time. Defaults to 150. + type: + - integer + - 'null' + track_invalid_requests: + description: Whether or not to track invalid requests. An invalid request is a request that came in that no router existed for. Usually this means bot requests. Defaults to false. + type: + - boolean + - 'null' + ignore_paths: + description: An array of paths to exclude from tracking. + type: + - array + - 'null' + items: + type: string + UdpTransportConfig: + title: UdpTransportConfig + description: Additional configuration options for the UDP transport mode. + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - udp + details: + type: object + required: + - telemetry + properties: + telemetry: + type: object + description: Configuration options for how telemetry is handled on the load balancer. + additionalProperties: {} + HybridIdentifier: + title: HybridIdentifier + type: string + description: Either a resource ID (objectid - i.e. 651586fca6078e98982dbd90) or a resource Identifier (human-readable) + examples: + - my-image-source + TcpRouterConfig: + title: TcpRouterConfig + description: Additional configuration options for TCP mode routers + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - tcp + details: + type: object + additionalProperties: {} + UdpRouterConfig: + title: UdpRouterConfig + description: Additional configuration options for UDP mode routers + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - udp + details: + type: object + additionalProperties: {} + HttpRouterConfig: + title: HttpRouterConfig + description: Additional configuration options for HTTP mode routers. + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - http + details: + type: object + properties: + redirect: + type: + - object + - 'null' + required: + - auto_https_redirect + - remove_www + description: Defines a built-in redirect for HTTP mode routers + properties: + auto_https_redirect: + type: boolean + description: If enabled and a sibling controller exists for port 443, requests will be auto redirected to it. Essentially sets up automatic TLS redirection for this router. + remove_www: + description: If true, any request comes in with "www" prefix will be permanently redirected to the same path without www. + type: boolean + port: + type: + - integer + - 'null' + description: The port to redirect traffic to. + scheme: + type: + - string + - 'null' + description: The scheme to redirect to. (i.e. `https`) + url: + type: + - string + - 'null' + description: A specific URL to redirect to. + forward: + type: + - object + - 'null' + properties: + scheme: + type: + - string + - 'null' + content_mod: + description: Allows the load balancer to modify content before it reaches the user. + type: + - object + - 'null' + properties: + replace: + description: An array that describes a list of replacement match/value pairs. + type: + - array + - 'null' + items: + type: object + required: + - match + - value + properties: + match: + description: String that will be replaced. + type: string + value: + description: Replacement value. + type: string + url: + type: + - string + - 'null' + description: | + The URL to forward the request to. + + Given a path match of `^/example/(.*)$`, a route such as `/example/wow.jpg` would be forwarded as /wow.jpg. + examples: + - /$$1 + proxy: + type: + - object + - 'null' + properties: + domain: + type: + - string + - 'null' + description: The domain that this router will proxy. + url: + description: The full URL that this router will proxy. + type: + - string + - 'null' + content_mod: + description: Allows the load balancer to modify content before it reaches the user. + type: + - object + - 'null' + properties: + replace: + description: An array that describes a list of replacement match/value pairs. + type: + - array + - 'null' + items: + type: object + required: + - match + - value + properties: + match: + description: String that will be replaced. + type: string + value: + description: Replacement value. + type: string + caching: + type: + - object + - 'null' + properties: + files: + type: + - array + - 'null' + items: + type: object + required: + - match + - ttl + properties: + match: + description: Regex string that describes the files to cache. + examples: + - (.*)\.(js|jpg|css|png|svg)$ + type: string + ttl: + description: Time string that describes the time to live. + $ref: '#/components/schemas/Duration' + V1LbConfigRouter: + title: V1LbRouterConfig + description: A specific router configuration that describes how traffic matching the rule is handled. + type: object + required: + - match + - mode + - config + properties: + match: + type: object + description: The ruleset for this router to be selected. If both `domains`` and `internal_port` are null, then this match acts as a wildcard and will match all. + required: + - domains + - internal_ports + properties: + domains: + description: The specific domains to match against. + oneOf: + - type: array + items: + type: string + - type: 'null' + internal_ports: + description: The specific ports to match against. + oneOf: + - type: array + items: + type: integer + - type: 'null' + path: + type: + - string + - 'null' + containers: + type: + - object + - 'null' + description: Match traffic destined (or not destined) for a particular container. + properties: + include: + description: Match any traffic that would be routed to one of these containers. + oneOf: + - type: array + items: + $ref: '#/components/schemas/HybridIdentifier' + - type: 'null' + exclude: + description: Match any traffic that would NOT be routed to one of these containers. + oneOf: + - type: array + items: + $ref: '#/components/schemas/HybridIdentifier' + - type: 'null' + mode: + type: string + description: | + How to route the traffic to the destination. + `random`: Pick a valid destination at random. + `round-robin`: Send each request to the 'next' destination on the list, restarting from the beginning when the last destination is used. + `source-ip`: Utilizes a hash function to ensure traffic from an IP will always hit the same destination instance. + enum: + - random + - round-robin + - source-ip + config: + type: object + required: + - sticky_sessions + - destination_retries + - timeouts + properties: + sticky_sessions: + type: boolean + description: If a request comes in from the same origin, ensure it hits the same destination. + destination_retries: + type: integer + description: If a destination is unavailable, retry up to [x] times, instead of immediately failing with a 503/504 error. + destination_prioritization: + oneOf: + - type: string + description: | + Hints to the load balancer how to prioritize traffic to instances. + **random**: Chooses a random instance. **latency**: Prioritizes lower latency instances. **fixed**: The order of the destinations will be the same regardless of instance or load balancer location. Used primarily with source IP routing. + enum: + - latency + - random + - fixed + - type: 'null' + tls: + type: + - object + - 'null' + description: TLS termination configuration. If null, the platform will use the default configuration. Port 443 by default has TLS termination enabled. + properties: + server_name: + type: + - string + - 'null' + description: | + [Advanced] Change the domain the controller listens on. + allow_insecure: + type: + - boolean + - 'null' + description: If enabled, accept TLS traffic with an invalid certificate. This is usually done for development/testing, and is not recommended for production use. + client_cert_auth: + description: A PEM encoded string of certificates. + type: + - string + - 'null' + client_auth: + description: | + Defines how to validate the connecting TLS certificate. + `none`: Do not require a TLS certificate to be sent + `request`: Asks the client to send a TLS certificate, but does not require nor validate it. + `require`: Requires a certificate be sent for the request to be valid, but does not validate the certificate. + `require-verify`: Requires both that the client send a certificate, and that the certificate is valid. This is required when using https. + oneOf: + - type: string + enum: + - none + - request + - require + - require-verify + - type: 'null' + timeouts: + type: object + description: Defines how the length of various sorts of timeouts when communicating with the destination. + required: + - destination_connection + properties: + destination_connection: + $ref: '#/components/schemas/Duration' + description: The duration the load balancer will wait before timing out while attempting to connect to the destination. + extension: + anyOf: + - type: 'null' + - type: object + description: Additional configuration options specific to the selected mode (tcp/http). + discriminator: + propertyName: type + mapping: + tcp: '#/components/schemas/TcpRouterConfig' + udp: '#/components/schemas/UdpRouterConfig' + http: '#/components/schemas/HttpRouterConfig' + oneOf: + - $ref: '#/components/schemas/TcpRouterConfig' + - $ref: '#/components/schemas/HttpRouterConfig' + - $ref: '#/components/schemas/UdpRouterConfig' + V1LbController: + title: V1LbController + type: object + required: + - identifier + - port + properties: + identifier: + type: string + description: A human-readable identifier for this controller. It will default to the port, i.e. `port-443`, but can be renamed to anything, such as the service this controller represents. + port: + type: integer + description: The port inbound trafic is accepted on. + waf: + anyOf: + - $ref: '#/components/schemas/WafConfig' + - type: 'null' + transport: + title: V1LbControllerTransport + description: Defines how traffic comes in to the load balancer, and how the load balancer handles it. + oneOf: + - type: 'null' + - type: object + required: + - mode + - config + - routers + - disable + properties: + disable: + type: boolean + description: When true, this controller is disabled and will not be used. + mode: + type: string + description: The kind of traffic (http/tcp/udp) that will be sent to the load balancer. + enum: + - tcp + - udp + - http + config: + type: object + description: Defines how the transport for this controller operates. + required: + - performance + - ingress + - timeouts + - verbosity + properties: + performance: + type: boolean + description: | + Enable/disable performance mode. If enabled, some telemetry will be disabled to dedicate full processing to handling requests. + You will not see per-request breakdowns or URL logging if performance mode is enabled. + ingress: + type: object + description: Defines how traffic gets into the load balancer. + properties: + tls: + type: + - object + - 'null' + required: + - enable + properties: + enable: + type: boolean + description: Enables or disables TLS. + timeouts: + type: object + description: Defines settings for various types of timeouts. + required: + - idle + properties: + idle: + description: The total amount of time a connection can be idle before being killed. + $ref: '#/components/schemas/Duration' + verbosity: + type: string + description: Verbosity describes the level of logging detail for the controller + enum: + - low + - normal + - high + - debug + extension: + type: object + description: Extended configurations for the specified transport mode (http/tcp) + discriminator: + propertyName: type + mapping: + tcp: '#/components/schemas/TcpTransportConfig' + http: '#/components/schemas/HttpTransportConfig' + udp: '#/components/schemas/UdpTransportConfig' + oneOf: + - $ref: '#/components/schemas/TcpTransportConfig' + - $ref: '#/components/schemas/HttpTransportConfig' + - $ref: '#/components/schemas/UdpTransportConfig' + routers: + type: array + description: Defines where traffic is sent. Many can be defined per controller. + items: + $ref: '#/components/schemas/V1LbConfigRouter' + V1LbConfig: + title: V1LbConfig + type: object + required: + - controllers + properties: + controllers: + type: array + description: A configuration for a specific port. + items: + $ref: '#/components/schemas/V1LbController' + controller_template: + anyOf: + - $ref: '#/components/schemas/V1LbController' + - type: 'null' + waf: + anyOf: + - $ref: '#/components/schemas/WafConfig' + - type: 'null' + V1LbType: + title: V1LbType + type: object + required: + - type + - details + - ipv4 + - ipv6 + - performance + properties: + performance: + type: boolean + description: Enable / disable performance mode. If enabled, load balancer can use much more RAM and CPU. + ipv4: + type: boolean + description: Allow / disallow traffic to be routed via IPv4. + ipv6: + type: boolean + description: Allow / disallow traffic to be routed via IPv6. + type: + type: string + enum: + - v1 + details: + $ref: '#/components/schemas/V1LbConfig' + DefaultLbType: + title: DefaultLbType + type: object + required: + - type + - details + - ipv4 + - ipv6 + - performance + properties: + performance: + type: boolean + description: Enable / disable performance mode. If enabled, load balancer can use much more RAM and CPU. + ipv4: + type: boolean + description: Allow / disallow traffic to be routed via IPv4. + ipv6: + type: boolean + description: Allow / disallow traffic to be routed via IPv6. + type: + type: string + enum: + - default + details: + oneOf: + - $ref: '#/components/schemas/HaProxyConfig' + - $ref: '#/components/schemas/V1LbConfig' + - type: 'null' + LoadBalancerConfig: + title: LoadBalancerConfig + type: object + description: The config object for the loadbalancer service. + discriminator: + propertyName: type + mapping: + haproxy: '#/components/schemas/HaProxyLbType' + v1: '#/components/schemas/V1LbType' + default: '#/components/schemas/DefaultLbType' + oneOf: + - $ref: '#/components/schemas/V1LbType' + - $ref: '#/components/schemas/HaProxyLbType' + - $ref: '#/components/schemas/DefaultLbType' + LoadBalancerEnvironmentService: + title: LoadBalancerEnvironmentService + type: object + description: Information about the environments loadbalancer service(s). + required: + - enable + - container_id + - high_availability + properties: + enable: + type: boolean + description: Whether or not the loadbalancer service is enabled. + container_id: + type: + - string + - 'null' + description: The ID of the loadbalancer service container + high_availability: + type: boolean + description: A boolean representing if this service container is set to high availability mode or not. + auto_update: + type: boolean + description: A boolean representing if this service container is set to autoupdate or not + config: + anyOf: + - $ref: '#/components/schemas/LoadBalancerConfig' + - type: 'null' + DiscoveryConfig: + title: DiscoveryConfig + type: object + description: The config object for the discovery service. + properties: + empty_set_delay: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + hosts: + description: A mapping of hostnames to IP addresses for custom internal resolutions. Acts as a custom /etc/resolv.conf file that works environment wide. + oneOf: + - type: object + additionalProperties: + type: object + properties: + ipv4: + description: The IPv4 address the discovery server should return to any container instance requesting this hostname. + type: + - array + - 'null' + items: + type: string + ipv6: + description: The IPv6 address the discovery server should return to any container instance requesting this hostname. + type: + - array + - 'null' + items: + type: string + - type: 'null' + custom_resolvers: + description: A list of custom DNS resolver strings. Can specifify domains or ips. + oneOf: + - type: array + items: + type: string + - type: 'null' + dual_stack_legacy: + description: When enabled, discovery will return both IPv6 and IPv4 when in legacy mode. Otherwise, only IPv4 will be returned. + anyOf: + - type: boolean + - type: 'null' + external_resolution: + anyOf: + - type: object + required: + - preference + properties: + preference: + type: string + enum: + - default + - ipv4 + - ipv6 + - type: 'null' + domain_suffix: + anyOf: + - type: string + - type: 'null' + DiscoveryEnvironmentService: + title: DiscoveryEnvironmentService + type: object + description: Information about the environments discovery service(s). + required: + - enable + - container_id + - high_availability + properties: + enable: + type: boolean + description: Whether or not the discovery service is enabled. + container_id: + type: string + description: The ID of the discovery service container + high_availability: + type: boolean + description: A boolean representing if this service container is set to high availability mode or not. + auto_update: + type: boolean + description: A boolean where `true` represents the desire to automatically update the environment discovery service. + config: + description: The config object for the discovery service. + anyOf: + - $ref: '#/components/schemas/DiscoveryConfig' + - type: 'null' + VpnEnvironmentService: + title: VpnEnvironmentService + type: object + description: Information about the environments vpn service(s). + required: + - enable + - container_id + - high_availability + properties: + enable: + type: boolean + description: Whether or not the VPN service is enabled. + container_id: + type: string + description: The ID of the VPN service container + auto_update: + type: boolean + description: A boolean representing if this service container is set to autoupdate or not + config: + description: The config object for the VPN service. + oneOf: + - type: object + required: + - allow_internet + - auth + properties: + allow_internet: + type: boolean + description: If true, routes all traffic through the VPN, even non-Cycle traffic. + custom_directives: + type: + - string + - 'null' + description: | + Additional OpenVPN directives that will be appended to the server configuration on service start. Each line should follow standard OpenVPN syntax. + examples: + - | + client-to-client + duplicate-cn + persist-key + persist-tun + - | + verb 3 + mute 10 + auth: + type: object + description: Auth configuration for the VPN. + required: + - webhook + - cycle_accounts + properties: + webhook: + type: + - string + - 'null' + description: A webhook endpoint to hit. Will be passed the login credentials provided to the user, and should return a 200 status if the login is permitted. + cycle_accounts: + type: boolean + description: If true, allows any Cycle account with access to the environment to log in to the VPN using their Cycle email and password. + vpn_accounts: + type: boolean + description: If true, allows the custom VPN accounts to log in to the VPN. + - type: 'null' + SchedulerAccessKey: + title: SchedulerAccessKey + description: Custom authorization keys for the scheduler service. + type: object + required: + - name + - secret + properties: + name: + type: string + description: The name given to this access key + secret: + type: string + description: The access key secret. This should be submitted with requests to a publicly accessible scheduler service. + ips: + type: array + description: Whitelisted IPs that are allowed to make requests to the scheduler service. + items: + type: string + SchedulerConfig: + title: SchedulerConfig + description: Configuration options for the scheduler Environment service. + type: object + required: + - public + properties: + public: + type: boolean + description: | + If true, this scheduler will be accessible over the public internet. It will enable a LINKED record to be pointed to the scheduler container, and inbound requests to trigger function containers. + access_keys: + type: array + items: + $ref: '#/components/schemas/SchedulerAccessKey' + SchedulerEnvironmentService: + title: SchedulerEnvironmentService + type: object + description: Information about the environments scheduler service. The scheduler is used by containers with a function deployment strategy to route requests to the correct instances. + required: + - enable + - container_id + - high_availablity + properties: + enable: + type: boolean + description: Whether or not the scheduler service is enabled. + container_id: + type: + - string + - 'null' + description: The ID of the scheduler service container. + high_availability: + type: boolean + description: A boolean representing if the scheduler service container is set to high availability. mode or not. As of Jan 2024, this will always be false because HA is not availiable for the scheduler service. + auto_update: + type: boolean + description: A boolean where `true` represents the desire to automatically update the environment scheduler service. + config: + anyOf: + - $ref: '#/components/schemas/SchedulerConfig' + - type: 'null' + GatewayConfig: + title: GatewayConfig + type: object + required: + - ipv4 + - ipv6 + - performance + properties: + performance: + type: boolean + description: Enable / disable performance mode. If enabled, gateway can use much more RAM and CPU. + ipv4: + type: boolean + description: Allow / disallow traffic to be routed via IPv4. + ipv6: + type: boolean + description: Allow / disallow traffic to be routed via IPv6. + GatewayEnvironmentService: + title: GatewayEnvironmentService + type: object + description: Information about the environments gateway service(s). + required: + - enable + - container_id + - high_availability + properties: + enable: + type: boolean + description: Whether or not the gateway service is enabled. + container_id: + type: string + description: The ID of the gateway service container + high_availability: + type: boolean + description: | + A boolean representing if this service container is set to high availability + mode or not. + auto_update: + type: boolean + description: A boolean where `true` represents the desire to automatically update the environment gateway service. + config: + anyOf: + - $ref: '#/components/schemas/GatewayConfig' + - type: 'null' + EnvironmentServices: + title: EnvironmentServices + type: object + description: Service containers run by this environment and their configurations. + required: + - loadbalancer + properties: + loadbalancer: + anyOf: + - $ref: '#/components/schemas/LoadBalancerEnvironmentService' + - type: 'null' + discovery: + anyOf: + - $ref: '#/components/schemas/DiscoveryEnvironmentService' + - type: 'null' + vpn: + anyOf: + - $ref: '#/components/schemas/VpnEnvironmentService' + - type: 'null' + scheduler: + anyOf: + - $ref: '#/components/schemas/SchedulerEnvironmentService' + - type: 'null' + gateway: + anyOf: + - $ref: '#/components/schemas/GatewayEnvironmentService' + - type: 'null' + ACL: + title: ACL + description: An access control list. Defines which roles have which permissions on specific resources. + type: object + properties: + roles: + type: object + additionalProperties: + type: object + title: ACLEntry + description: Permissions for an ACL entry. + required: + - view + - modify + - manage + properties: + view: + type: boolean + description: Can the user see / use this resource? + modify: + type: boolean + description: Can the user edit the state / name / identifier of this resource? + manage: + type: boolean + description: Can the user delete / update ACLs for this resource? + IPNet: + title: IPNet + type: object + required: + - ip + - cidr + properties: + ip: + type: string + description: The IP address. + examples: + - fd00::21:0:0:0 + cidr: + type: string + description: The CIDR notation, describing the range of IP addresses. + examples: + - fd00::21:0:0:0/96 + LegacyNetwork: + title: LegacyNetwork + type: object + description: Legacy network information for an environment. + required: + - subnet + properties: + subnet: + type: integer + description: The IPv4 subnet id. + ipv4: + description: IPv4 information available from environments using legacy networking. + anyOf: + - $ref: '#/components/schemas/IPNet' + - type: 'null' + PrivateNetwork: + title: PrivateNetwork + type: object + required: + - vxlan_tag + - subnet + - ipv6 + - legacy + properties: + vxlan_tag: + type: integer + description: The vxlan tag added to each packet to help identify the network. + subnet: + type: string + description: The subnet ID. + ipv6: + allOf: + - description: The IPv6 interface. + - $ref: '#/components/schemas/IPNet' + legacy: + anyOf: + - $ref: '#/components/schemas/LegacyNetwork' + - type: 'null' + Version: + title: Version + type: string + description: | + Version can be any string, but if it begins with a "v", semantic version will be enforced. A [Semantic Version](https://semver.org/) string. Follows the format vMAJOR.MINOR.PATCH-build. + examples: + - v1.2.3-dev + EnvironmentDeploymentTags: + title: EnvironmentDeploymentTags + type: object + description: | + A map of custom tags to deployment versions. Allows for defining a custom, persistent tag with a changing version number. + For example, `dev -> v1.2.3-dev`. This is useful when dealing with DNS LINKED records, where you always want dev.example.com to point to the + `dev` version of your app within an environment, where you can continuously deploy and update it without needing to change the record. It is + even more useful when you have multiple LINKED records, and you update i.e. `prod`` tag to point to a new version, all records using the `prod` tag + are switched at once. + additionalProperties: + $ref: '#/components/schemas/Version' + StateCountSummary: + title: ResourceCountSummary + type: object + description: A summary of resources by state + required: + - state + - total + - available + properties: + state: + title: CountsByState + type: object + description: A count of this resource, grouped by state. + additionalProperties: + type: integer + total: + type: integer + description: The total number of this resource + available: + type: integer + description: The total number of this resource available, less any deleted ones. + example: + state: + new: 0 + starting: 0 + running: 5 + stopping: 0 + deleting: 0 + deleted: 0 + total: 5 + available: 5 + ContainerState: + title: ContainerState + allOf: + - required: + - current + properties: + current: + description: The current state of the container. + type: string + enum: + - new + - starting + - running + - function + - stopping + - stopped + - deleting + - deleted + desired: + description: The desired state of the container. + type: string + enum: + - new + - starting + - running + - function + - stopping + - stopped + - deleting + - deleted + - $ref: '#/components/schemas/State' + ContainerImageSummary: + title: ContainerImageSummary + description: The Id of the image and information on if it is a service. + type: object + required: + - id + - service + properties: + id: + $ref: '#/components/schemas/ID' + service: + anyOf: + - type: string + description: If this image is a service container this will say either `discovery` | `loadbalancer` | `vpn`. + enum: + - discovery + - loadbalancer + - vpn + - type: 'null' + ContainerEnvironmentSummary: + title: ContainerEnvironmentSummary + description: A summary of supplemental environment and network information specific to a container. + type: object + required: + - id + - cluster + properties: + id: + $ref: '#/components/schemas/ID' + cluster: + type: string + description: The cluster this environment is associated with. + container_subnet: + type: + - string + - 'null' + description: The private network subnet ID for this container and its instances. + ipv6: + anyOf: + - $ref: '#/components/schemas/IPNet' + - type: 'null' + legacy: + anyOf: + - $ref: '#/components/schemas/LegacyNetwork' + - type: 'null' + EnvironmentMeta: + title: EnvironmentMeta + type: object + description: A list of meta fields that can be applied to this environment. + properties: + containers_count: + $ref: '#/components/schemas/StateCountSummary' + instances_count: + $ref: '#/components/schemas/StateCountSummary' + containers: + type: array + items: + type: object + required: + - id + - name + - state + - image + - environment + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: A user defined name for the container resource. + state: + $ref: '#/components/schemas/ContainerState' + image: + $ref: '#/components/schemas/ContainerImageSummary' + environment: + $ref: '#/components/schemas/ContainerEnvironmentSummary' + service_versions: + description: A map where the key is the service and the value describes the version and date of last update. + type: object + additionalProperties: + type: array + items: + type: object + required: + - version + - last_updated + properties: + version: + description: A string depicting the service version. + example: v2025.01.01.01 + type: string + instance_id: + description: The ID of the instance of the service. + $ref: '#/components/schemas/ID' + last_updated: + description: The time the version was last updated. + $ref: '#/components/schemas/DateTime' + Environment: + title: Environment + type: object + description: Environments are groups of containers with a private network built between them. For more information on environments, see the [main docs](https://cycle.io/docs/platform/introduction-to-environments). + required: + - id + - identifier + - name + - cluster + - about + - creator + - hub_id + - state + - events + - features + - services + properties: + id: + $ref: '#/components/schemas/ID' + identifier: + $ref: '#/components/schemas/Identifier' + description: A human readable slugged identifier for this environment. + name: + type: string + description: A user defined name for the environment resource. + cluster: + type: string + description: The cluster this environment is associated with. + about: + $ref: '#/components/schemas/EnvironmentAbout' + creator: + $ref: '#/components/schemas/CreatorScope' + hub_id: + $ref: '#/components/schemas/HubID' + state: + $ref: '#/components/schemas/EnvironmentState' + events: + title: EnvironmentEvents + type: object + description: A collection of timestamps for each event in the environment's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the environment was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the environment was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the environment was deleted. + $ref: '#/components/schemas/DateTime' + features: + $ref: '#/components/schemas/EnvironmentFeatures' + services: + $ref: '#/components/schemas/EnvironmentServices' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + private_network: + anyOf: + - $ref: '#/components/schemas/PrivateNetwork' + - type: 'null' + deployments: + description: | + A map of custom tags to deployment versions. + oneOf: + - type: object + required: + - tags + properties: + tags: + $ref: '#/components/schemas/EnvironmentDeploymentTags' + - type: 'null' + meta: + $ref: '#/components/schemas/EnvironmentMeta' + ContainerExtension: + title: ContainerExtension + type: + - object + - 'null' + description: Reference to container functionality that is added by the Cycle platform. + required: + - identifier + properties: + identifier: + type: string + enum: + - virtual-machine-v1 + id: + $ref: '#/components/schemas/ID' + ServiceContainerIdentifier: + title: ServiceContainerIdentifier + type: string + description: Identifier of a service Container within an Environment. + enum: + - discovery + - vpn + - loadbalancer + - scheduler + - gateway + ImageSummary: + title: ContainerImageSummary + description: A summary of the image this container was created from. + type: object + required: + - id + - service + - extension + properties: + id: + anyOf: + - $ref: '#/components/schemas/ID' + - type: 'null' + extension: + anyOf: + - $ref: '#/components/schemas/ContainerExtension' + - type: 'null' + service: + anyOf: + - $ref: '#/components/schemas/ServiceContainerIdentifier' + - type: 'null' + description: If a service container, the identifier specifying which service it is. + StackSummary: + title: ContainerStackSummary + description: A summary of the stack this container was created format. + type: object + properties: + id: + $ref: '#/components/schemas/ID' + build_id: + type: string + description: The ID of the stack build this container is associated with. + identifier: + type: string + description: The container identifier, usually the key to the container section of a stack file. + Cidr: + title: Cidr + type: string + format: cidr + description: | + A CIDR (Classless Inter-Domain Routing) string is a notation used to represent an IP address and its associated network prefix. + It combines an IP address with a suffix that indicates how many bits are fixed for routing. + examples: + - 192.168.1.0/24 + IpAddress: + title: IpAddress + type: string + format: ip-address + description: | + An IP address is a numerical label that uniquely identifies a device on a network and enables it to send and receive data. + examples: + - 192.168.1.1 + NetworkRouteConfigNexthop: + title: NetworkRouteConfigNexthop + type: object + description: A single next hop for a multipath network route. + required: + - gateway + properties: + gateway: + description: The IP address of this next hop's gateway. + $ref: '#/components/schemas/IpAddress' + hop_weight: + description: The relative weight of this next hop when distributing traffic across multiple next hops. + oneOf: + - type: integer + format: int64 + - type: 'null' + NetworkRouteConfig: + title: NetworkRouteConfig + type: object + description: A single network route directing traffic for a destination network. + required: + - destination + - source + - ensure_source_exists + - gateway + - interface + properties: + destination: + description: The destination network, in CIDR notation, that this route matches. + oneOf: + - $ref: '#/components/schemas/Cidr' + - type: 'null' + source: + description: The source network, in CIDR notation, that this route applies to. + oneOf: + - $ref: '#/components/schemas/Cidr' + - type: 'null' + ensure_source_exists: + type: boolean + description: When true, the source address is verified to exist on the host before this route is applied. + family: + description: The IP protocol family this route applies to. + oneOf: + - type: string + enum: + - ipv4 + - ipv6 + - type: 'null' + gateway: + description: The IP address that traffic matching the destination is forwarded to. + $ref: '#/components/schemas/IpAddress' + nexthops: + type: array + description: Additional next hops for this route, used for multipath (ECMP) routing. + items: + $ref: '#/components/schemas/NetworkRouteConfigNexthop' + interface: + type: string + description: The name of the network interface this route is bound to. + L2Domain: + title: L2Domain + description: | + A standardized name for different layer-2 networks that can be configured on virtual provider hosts. + Containers will utilize this name to determine which network to attach to on the host, if set in the config. + type: string + enum: + - public + - shared + - private + ContainerNetwork: + title: ContainerNetwork + type: object + description: Network configuration for a container. + required: + - public + - egress_via_gateway + - routes + - hostname + properties: + public: + type: string + description: The public network settings for the given container. + enum: + - enable + - egress-only + - environment-limited + - disable + egress_via_gateway: + type: boolean + description: When true, the container's egress traffic is routed out through the environment gateway. + routes: + type: + - array + - 'null' + description: Custom network routes applied to the container's instances. + items: + $ref: '#/components/schemas/NetworkRouteConfig' + hostname: + type: string + description: The hostname for the given container. + ports: + type: array + items: + type: string + description: An array of port mappings for the container. + l2: + description: Layer 2 network configuration options for containers running on virtual provider servers. + oneOf: + - type: object + required: + - domains + properties: + domains: + type: array + description: | + The layer 2 'domains' that this container's instances should bridge to on the host server. + If the host has a matching layer 2 NIC configured via a virtual provider ISO, this container's instances + will be joined directly to the host's network. + items: + $ref: '#/components/schemas/L2Domain' + DeploymentStrategyName: + title: DeploymentStrategyName + type: string + enum: + - resource-density + - high-availability + - distributed + - first-available + - manual + - node + - edge + - function + ContainerDeployHighAvailabilityConfig: + title: ContainerDeployHighAvailabilityConfig + description: Configuration options for how the platform treats instances of this container when opting into high availability via the internal API. + required: + - stale_primary_deadline + properties: + stale_primary_deadline: + description: The amount of time that must pass between high availability checkins before an instance is considered stale. If it is the primary, a new primary will be elected after this deadline. Minimum is 15s. + $ref: '#/components/schemas/Duration' + Crontab: + title: Crontab + type: string + format: crontab + description: | + A crontab string defines a recurring schedule. + + In standard form it consists of five space-separated fields specifying, in + order, the minute (0-59), hour (0-23), day of the month (1-31), month + (1-12), and day of the week (0-6, where 0 is Sunday). Each field accepts a + specific value, a wildcard (`*`), a range (`1-5`), a list (`1,15,30`), or a + step (`*/5`). + + An optional leading seconds field (0-59) may be included, producing a + six-field form. + + Predefined macros are also accepted in place of the fields: `@yearly` + (equivalent to `@annually`), `@monthly`, `@weekly`, `@daily` (equivalent to + `@midnight`), and `@hourly`, as well as `@every ` where duration + is a duration string such as `5m` or `1h30m`. + examples: + - '*/5 * * * *' + - 0 0 * * * + - 30 9 * * 1-5 + - '*/30 * * * * *' + - '@daily' + - '@every 5m' + ShutdownSignal: + title: ShutdownSignal + type: string + description: Process signals that Cycle can be configured to send to the container on a shutdown event. + enum: + - SIGTERM + - SIGINT + - SIGUSR1 + - SIGUSR2 + - SIGHUP + - SIGQUIT + ContainerDeploy: + title: ContainerDeploy + type: object + description: Deployment configuration for the given container. + required: + - instances + properties: + instances: + type: integer + description: The number of initial desired instances for a given container. + strategy: + oneOf: + - $ref: '#/components/schemas/DeploymentStrategyName' + - type: 'null' + description: The deployment strategy to use when scaling the given container. + ha_elections: + description: Configuration options for how the platform treats instances of this container when opting into high availability elections via the internal API. + oneOf: + - $ref: '#/components/schemas/ContainerDeployHighAvailabilityConfig' + - type: 'null' + function: + description: Configuration options for containers using the 'function' deployment strategy. + oneOf: + - type: object + properties: + max_pool_size: + description: The maximum number of instances that Cycle can pre-allocate (includes auto-scaled instances). + type: + - integer + - 'null' + max_shard_concurrency: + description: For each shard (scheduler), the maximum number of tasks it can run in parallel. + type: + - integer + - 'null' + max_runtime: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: The maximum amount of time a function instance can run before timing out. + max_queue_time: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: The maximum amount of time Cycle will wait for an instance to be available. + schedule: + anyOf: + - $ref: '#/components/schemas/Crontab' + - type: 'null' + description: A recurring schedule on which function instances are automatically triggered. When null, the function runs only on explicit invocation. + - type: 'null' + stateful: + description: Configuration options for stateful deployments. + oneOf: + - type: object + properties: + options: + description: Options that modify behavior for stateful deployments. + oneOf: + - type: object + properties: + use_base_hostname: + description: When set, the base hostname will be used instead of a generated hostname. + type: + - boolean + - 'null' + - type: 'null' + - type: 'null' + constraints: + description: Settings that give more granular control over deployment targets and conditions. + oneOf: + - type: object + properties: + node: + oneOf: + - type: object + description: Constraint settings related to which nodes an instance can be deployed to. + required: + - tags + properties: + tags: + type: object + description: Lists of server tags that formally declair servers that match the criteria for deployment. + properties: + any: + type: + - array + - 'null' + items: + type: string + description: A list of tags where a server matching any tags from the list is qualified as a deployment target. + all: + type: + - array + - 'null' + items: + type: string + description: A list of tags where a server matching all tags from the list is the only scenario where the server is qualified as a deployment target. + - type: 'null' + secrets: + description: A list of secret identifiers that will be made available to the container. + type: + - array + - 'null' + items: + type: string + - type: 'null' + shutdown: + description: Configuration for what to do during container shutdown. + oneOf: + - type: object + properties: + graceful_timeout: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: How long the platform will wait for a container to stop gracefully. + signals: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/ShutdownSignal' + description: Process signal sent to the container process. + - type: 'null' + startup: + description: Configurations for container startup. + oneOf: + - type: object + properties: + delay: + $ref: '#/components/schemas/Duration' + description: How long the platform will wait before sending the start signal to the given container. + - type: 'null' + update: + description: Configurations for container updates. + oneOf: + - type: object + properties: + stagger: + $ref: '#/components/schemas/Duration' + description: When set, Cycle will pick a random time from `0 - this duration`, and stagger the instances so they all start at different times (up to the time specified here). + - type: 'null' + restart: + description: Configurations for container restart events. + oneOf: + - type: object + required: + - condition + - delay + - max_attempts + properties: + condition: + type: string + description: Policy for what should happen in the event of a container dying. + enum: + - always + - never + - failure + delay: + $ref: '#/components/schemas/Duration' + description: How long the platform will wait before trying to restart the container. + max_attempts: + type: integer + description: The amount of times the platform will attempt the restart policies. + - type: 'null' + readiness_check: + description: Configuration for determining readiness of a container. + oneOf: + - type: object + required: + - command + - interval + - timeout + properties: + command: + type: string + description: The command that will be run to verify readiness of the container. + interval: + $ref: '#/components/schemas/Duration' + timeout: + $ref: '#/components/schemas/Duration' + - type: 'null' + health_check: + description: Configuration for determining the health of a container. + oneOf: + - type: object + required: + - command + - retries + - delay + - interval + - timeout + - restart + properties: + command: + type: string + description: The command that will be run to verify the health of the container. + retries: + type: integer + description: The number of times the platform will retry the command before marking the container unhealthy. + delay: + $ref: '#/components/schemas/Duration' + description: How long to wait before performing an initial health check when the instance starts. The `state.health.healthy` field of the instance will be `null`` until the first check is performed. + interval: + $ref: '#/components/schemas/Duration' + description: How long to wait between restarts. + timeout: + $ref: '#/components/schemas/Duration' + description: How long before a health check attempt times out. + restart: + type: boolean + description: A boolean where `true` represents the desire for a container to restart if unhealthy. + - type: 'null' + telemetry: + description: Configuration settings for container telemetery reporting. + oneOf: + - type: object + required: + - retention + - interval + - disable + properties: + retention: + $ref: '#/components/schemas/Duration' + description: How long telemetry data should be retained. + interval: + $ref: '#/components/schemas/Duration' + description: The duration between samples. + disable: + type: boolean + description: A boolean where true disables all telemetry reporting for this container. + - type: 'null' + ScaleThresholdMetricRam: + title: ScaleThresholdMetricRam + type: object + description: Describes the RAM threshold at which scaling will occur. + required: + - type + - details + properties: + type: + type: string + enum: + - ram + details: + type: object + required: + - usage + properties: + usage: + type: string + description: The target average RAM usage of all instances of this container. Going above this threshold will trigger a scaling event. This threshold must be greater than 25MB. + examples: + - 2G + - 25MB + ScaleThresholdMetricCpu: + title: ScaleThresholdMetricCpu + type: object + description: Describes the CPU threshold at which scaling will occur + required: + - type + - details + properties: + type: + type: string + enum: + - cpu + details: + type: object + required: + - utilization + properties: + utilization: + type: integer + WebhookURL: + title: WebhookURL + type: string + description: | + A URL describing the destination Cycle should send a POST webhook payload to. + examples: + - https://example.com/cycle/autoscale + ScaleThresholdMetricCustom: + title: ScaleThresholdMetricCustom + type: object + description: A custom threshold for defining a scaling event. + required: + - type + - details + properties: + type: + type: string + enum: + - custom + details: + type: object + required: + - webhook + properties: + webhook: + $ref: '#/components/schemas/WebhookURL' + ScaleThresholdMetricNetworkConnections: + title: ScaleThresholdMetricNetworkConnections + type: object + description: Describes the network connections threshold at which scaling will occur + required: + - type + - details + properties: + type: + type: string + enum: + - network-connections + details: + type: object + required: + - connections + properties: + connections: + type: integer + ScaleThresholdMetricNetworkRequests: + title: ScaleThresholdMetricNetworkRequests + type: object + description: Describes the network requests threshold at which scaling will occur + required: + - type + - details + properties: + type: + type: string + enum: + - network-requests + details: + type: object + required: + - requests + properties: + requests: + type: integer + ScaleThresholdMetricNetworkThroughput: + title: ScaleThresholdMetricNetworkThroughput + type: object + description: Describes the network throughput threshold at which scaling will occur + required: + - type + - details + properties: + type: + type: string + enum: + - network-throughput + details: + type: object + required: + - private + - bandwidth + properties: + private: + type: boolean + bandwidth: + type: string + description: The limit (maximum) amount of throughput each instance of the given container can use before triggering a scaling event. + examples: + - 1gbps + - 20mbps + ScaleThresholdMetric: + title: ScaleThresholdMetric + type: object + description: Discriminated union describing the different types of scaling threshold and their respective details + discriminator: + propertyName: type + mapping: + ram: '#/components/schemas/ScaleThresholdMetricRam' + cpu: '#/components/schemas/ScaleThresholdMetricCpu' + custom: '#/components/schemas/ScaleThresholdMetricCustom' + network-connections: '#/components/schemas/ScaleThresholdMetricNetworkConnections' + network-requests: '#/components/schemas/ScaleThresholdMetricNetworkRequests' + network-throughput: '#/components/schemas/ScaleThresholdMetricNetworkThroughput' + oneOf: + - $ref: '#/components/schemas/ScaleThresholdMetricRam' + - $ref: '#/components/schemas/ScaleThresholdMetricCpu' + - $ref: '#/components/schemas/ScaleThresholdMetricNetworkConnections' + - $ref: '#/components/schemas/ScaleThresholdMetricNetworkRequests' + - $ref: '#/components/schemas/ScaleThresholdMetricNetworkThroughput' + - $ref: '#/components/schemas/ScaleThresholdMetricCustom' + ContainerScale: + title: ContainerScale + type: object + description: Network configuration for a container. + required: + - autoscale_group + - instances + - window + - thresholds + properties: + autoscale_group: + type: + - string + - 'null' + description: The autoscaling group describes which servers should be deployed + instances: + type: object + description: Describes how many instances should be running + required: + - max + - max_server + - min_ttl + properties: + max: + type: integer + description: Maximum additional instances the auto-scaler will run at any time + max_server: + type: integer + description: Minimum number of instances per server + min_ttl: + $ref: '#/components/schemas/Duration' + description: Minimum amount of time an instance will live + window: + description: Duration in which the auto-scaler will watch for changes + $ref: '#/components/schemas/Duration' + thresholds: + description: An array of rules that dictate when a scaling event will be triggered + type: array + items: + $ref: '#/components/schemas/ScaleThresholdMetric' + RuntimeInternalApi: + title: RuntimeInternalApi + description: Configuration options for the internal API access within instances of this container. + type: object + properties: + scope: + oneOf: + - type: array + description: Scopes determine which set of endpoints instances of this container can reach over the internal API. + items: + type: string + enum: + - self + - environment + - networks + - server + - notifications + - type: 'null' + SeccompRule: + title: SeccompRule + description: Rules for controlling Linux seccomp inside a container. + type: object + properties: + capabilities: + type: object + properties: + includes: + type: string + excludes: + type: string + syscall: + type: object + description: LinuxSyscall is used to match a syscall in Seccomp + required: + - names + - action + properties: + names: + type: array + items: + type: string + action: + type: string + errnoRet: + type: integer + args: + type: array + items: + type: object + required: + - index + - value + - op + properties: + index: + type: integer + value: + type: integer + valueTwo: + type: integer + op: + type: string + RuntimeExposedDevice: + title: RuntimeExposedDevice + type: object + description: A host device exposed to the container during runtime. + required: + - source + - destination + properties: + source: + type: string + description: The path to the device on the host. + examples: + - /dev/kvm + - /dev/net/tun + destination: + type: string + description: The path inside the container that the device is mapped to. + examples: + - /dev/kvm + - /dev/net/tun + options: + anyOf: + - type: array + description: Options passed when mounting the device. + items: + type: string + examples: + - rbind + - ro + - type: 'null' + RuntimeDevicePermissionType: + title: RuntimeDevicePermissionType + type: string + description: | + The class of device this rule applies to (for example, block devices or character devices). + enum: + - b + - c + RuntimeDevicePermissionAccess: + title: RuntimeDevicePermissionAccess + type: string + description: | + The access mode permitted by this rule. Common conventions use a combination of letters (e.g., r, w, m) to indicate read, write, and mknod capabilities. + pattern: ^[rwm]+$ + examples: + - r + - rw + - rwm + RuntimeDevicePermission: + title: RuntimeDevicePermission + type: object + description: | + A rule that grants or denies access to a device node (e.g., Linux cgroup device rule). Controls which device type and major/minor numbers are allowed, and with what access. + required: + - type + - allow + - access + properties: + type: + $ref: '#/components/schemas/RuntimeDevicePermissionType' + major: + description: | + Device major number. + type: + - integer + - 'null' + format: int64 + minor: + description: | + Device minor number. + type: + - integer + - 'null' + format: int64 + allow: + type: boolean + description: Whether this rule allows (true) or denies (false) access. + access: + $ref: '#/components/schemas/RuntimeDevicePermissionAccess' + ContainerRuntime: + title: ContainerRuntime + type: object + description: Runtime configurations for a given container. + required: + - privileged + properties: + command: + description: A command that will be run in place of the images defined startup command. + oneOf: + - type: object + properties: + path: + type: + - string + - 'null' + description: System path for the command. + args: + type: + - string + - 'null' + description: Arguments to pass to the command. + - type: 'null' + namespaces: + type: array + items: + type: string + enum: + - ipc + - pid + - uts + - network + - mount + - user + - cgroup + description: Namespaces the given container will have access to. + environment_vars: + type: object + description: A record of environment variables for the given container. + additionalProperties: + type: string + privileged: + type: boolean + description: Selecting this option will give this container full permissions on the server. This is not recommended and increases the likelihood of your server being compromised. + capabilities: + type: array + items: + type: string + enum: + - CAP_CHOWN + - CAP_FSETID + - CAP_DAC_OVERRIDE + - CAP_FOWNER + - CAP_SETFCAP + - CAP_SETGID + - CAP_SETUID + - CAP_KILL + - CAP_MKNOD + - CAP_NET_BIND_SERVICE + - CAP_NET_RAW + - CAP_AUDIT_WRITE + - CAP_SYS_CHROOT + - CAP_SETPCAP + - CAP_DAC_READ_SEARCH + - CAP_NET_ADMIN + - CAP_NET_BROADCAST + - CAP_SYS_ADMIN + - CAP_SYS_MODULE + - CAP_SYS_NICE + - CAP_SYS_PACCT + - CAP_SYS_PTRACE + - CAP_SYS_RAWIO + - CAP_SYS_RESOURCE + - CAP_SYS_BOOT + - CAP_SYS_TIME + - CAP_SYS_TTY_CONFIG + - CAP_SYSLOG + - CAP_AUDIT_CONTROL + - CAP_AUDIT_READ + - CAP_IPC_LOCK + - CAP_IPC_OWNER + - CAP_LINUX_IMMUTABLE + - CAP_MAC_ADMIN + - CAP_MAC_OVERRIDE + - CAP_BLOCK_SUSPEND + - CAP_LEASE + - CAP_WAKE_ALARM + description: A list of linux kernel capabilites for the given container. + internal_api: + $ref: '#/components/schemas/RuntimeInternalApi' + workdir: + type: string + description: Configure the working directory for the given container. + sysctl: + type: object + description: A record of sysctl fields and values for a given container. + additionalProperties: + type: string + rlimits: + type: object + description: A record of rlimits and their values. + additionalProperties: + type: object + properties: + hard: + type: integer + description: The hard limit for the rlimit. + soft: + type: integer + description: The soft limit for the rlimit. + seccomp: + oneOf: + - type: object + properties: + disable: + type: boolean + rules: + type: array + items: + $ref: '#/components/schemas/SeccompRule' + - type: 'null' + host: + oneOf: + - type: object + properties: + expose_proc: + description: If true, Cycle will mount the `/proc` directory into the container, giving it access to the host metrics. This is useful if you're running i.e. a monitoring agent. + type: + - boolean + - 'null' + expose_cgroups: + description: If true, Cycle will mount the host's `/sys/fs/cgroups` directory into the container at `/var/run/cycle/host/cgroups`. + type: + - boolean + - 'null' + expose_instances_dir: + description: If true, Cycle will mount the host's instances directory into the container at `/var/run/cycle/host/instances`. + type: + - boolean + - 'null' + power_management: + description: If true, Cycle will give the container instances access via internal api to power off or reboot the host server. + type: + - boolean + - 'null' + - type: 'null' + rootfs: + type: object + properties: + readonly: + description: Enabling this option will set the containers filesystem to readonly. Volumes associated with the container will not be affected by this. + type: boolean + devices: + oneOf: + - type: object + properties: + shm_size: + type: + - string + - 'null' + description: The size of the shared host memory device (/dev/shm). + examples: + - 64M + - 128M + - 512M + expose: + anyOf: + - type: array + description: An array of devices to expose to the container. + items: + $ref: '#/components/schemas/RuntimeExposedDevice' + - type: 'null' + permissions: + anyOf: + - type: array + description: Rules for granting or denying access to a device node. + items: + $ref: '#/components/schemas/RuntimeDevicePermission' + - type: 'null' + - type: 'null' + ContainerResources: + title: ContainerResources + type: object + description: Configuration settings for the resource allocations and limits of a given container. + required: + - cpu + - ram + properties: + cpu: + type: object + description: Configurations settings related to CPU usage. + properties: + shares: + type: object + description: A share represents 1/10th of the available compute time on a single thread. + required: + - limit + - reserve + properties: + limit: + type: integer + description: The limit (maximum) amount of shares each instance of a container can use. + reserve: + type: integer + description: The reserve (allocation) number of shares for each instance of a given container. + cpus: + type: string + ram: + type: object + description: Configuration settings for limits and reserves of RAM resources for the given container. + properties: + limit: + type: string + description: The limit (maximum) amount of RAM each instance of the given container can use. + examples: + - 1G + - 1M + reserve: + type: string + description: The reserve (allocation) of RAM given to each instance of the container. + ContainerIntegrations: + title: ContainerIntegrations + type: object + description: Configuration settings for integrations with a given container. + properties: + webhooks: + type: object + description: Webhooks that can be set for specific event reporting and advanced container configurations. + properties: + events: + type: object + description: Container events that can be configured to report to a webhook. + properties: + deploy: + type: string + description: A webhook to hit when a container deploy event happens. + start: + type: string + description: A webhook to hit when a container start event happens. + stop: + type: string + description: A webhook to hit when a container stop event happens. + config: + type: string + description: An endpoint that the platform will react out to with a get request. This endpoint serves a partial container config which can modify `runtime`, `resources`, and `integrations` configurations. + files: + type: array + description: Inject remotely hosted files into container instances at runtime. + items: + type: object + description: These objects are sources and destinations for the given files. + required: + - source + - destination + properties: + source: + type: string + description: The http endpoint that is hosting the files to be used. + destination: + type: string + description: The path in the container for these files to be injected. + lets_encrypt: + description: Configuration settings to embed a TLS certificate in the container. + oneOf: + - type: object + properties: + certificate_path: + type: string + description: Path where the `certificate.cert` will be saved. + chain_path: + type: string + description: Path where the `certificate.chain` will be saved. + key_path: + type: string + description: Path where the `certificate.key` will be saved. + bundle_path: + type: string + description: Path where the `certificate.bundle` will be saved. + additional_certs_path: + type: string + description: File path where any remaining certificate files will be stored. + - type: 'null' + backups: + type: object + description: Automated backups configuration for the given container. + required: + - destination + - backup + - restore + - retention + properties: + integration_id: + $ref: '#/components/schemas/HybridIdentifier' + backup: + type: object + description: Configuration settings for each backup. + required: + - command + properties: + command: + type: string + description: The command to run for the backup. + timeout: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: How long the backup will attempt to run before timing out. + cron_string: + $ref: '#/components/schemas/Crontab' + description: A cron string that configures how often the backup will run. + restore: + type: + - object + - 'null' + description: Configuration settings for restoring from a backup. + required: + - command + properties: + command: + type: string + description: The command to run for restoring from a backup. + timeout: + type: string + description: The time in seconds for the restore to attempt to complete before timing out. + allOf: + - $ref: '#/components/schemas/Duration' + retention: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: How long the platform will keep backups. Default is 1 year. + default: 365d + shared_file_systems: + oneOf: + - type: object + additionalProperties: + type: object + required: + - writable + - mount_point + properties: + writable: + type: boolean + mount_point: + type: string + - type: 'null' + Config: + title: ContainerConfig + description: A container configuration. + type: object + required: + - network + - deploy + properties: + network: + $ref: '#/components/schemas/ContainerNetwork' + deploy: + $ref: '#/components/schemas/ContainerDeploy' + scale: + $ref: '#/components/schemas/ContainerScale' + runtime: + $ref: '#/components/schemas/ContainerRuntime' + resources: + $ref: '#/components/schemas/ContainerResources' + integrations: + $ref: '#/components/schemas/ContainerIntegrations' + Deployment: + title: Deployment + description: | + A logical grouping of containers inside of an Environment. Facilitates zero-downtime deployments by separating multiple versions of the same application within an environment. + + If a container is a member of a deployment, it can only resolve containers in that same deployment, or containers NOT in a deployment. If a container is NOT a member of a deployment, it can resolve all containers in the environment. + type: object + required: + - version + properties: + version: + $ref: '#/components/schemas/Version' + description: | + A version string representing the deployment. + DataSize: + title: DataSize + type: string + description: | + A human-readable data size string. Values are expressed as an integer followed by a unit suffix, without spaces. Supported units: + - b, k, m, g, t, p (bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes) + - An optional "b" suffix may be added (e.g., "mb", "gb"). + Units are case-insensitive. Example: "512M", "10GB", "1t". + pattern: ^[0-9]+([bBkKmMgGtTpP]|[kKmMgGtTpP][bB])$ + examples: + - 512M + - 10GB + - 1t + ContainerVolume: + title: ContainerVolume + type: object + description: Configuration settings for container volumes. + required: + - read_only + - block_device + - destination + properties: + identifier: + oneOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + read_only: + type: boolean + description: A boolean where true marks the volume as read only. + block_device: + type: boolean + description: | + Indicates that the volume will be used as unformatted block storage. + local: + oneOf: + - type: object + description: Configuration for settings local to the container filesystem. + required: + - max_size + properties: + max_size: + $ref: '#/components/schemas/DataSize' + description: The maximum size this volume can grow to. Container volumes on Cycle are thinly provisioned, meaning this isn't an allocation - the volume will only use the space it needs up to this size. + stateless: + type: + - boolean + - 'null' + default: false + description: | + If set to true, this volume will be treated as ephemeral. Stateless volumes will **NOT** be migrated. + Stateless volumes on stateful containers will be wiped on container stop. + storage_pool: + oneOf: + - type: boolean + description: A boolean where true signifies using the largest drive over 2TB for the target server. + - type: 'null' + - type: 'null' + external: + anyOf: + - type: object + properties: + id: + oneOf: + - $ref: '#/components/schemas/ID' + - type: 'null' + description: The id of the external volume. + - type: 'null' + destination: + type: string + description: The mountpoint path for the container. + remote_access: + type: object + description: Configuration settings for remotely accessing the container volume. + required: + - enable + - password + properties: + enable: + type: boolean + description: A boolean where true represents this container volume being open to remote access connections over SFTP. + ips: + type: array + items: + type: string + webhook: + type: string + description: Call out to a webhook to authenticate usernames/passwords if an organization manages their own accounts + password: + type: + - object + - 'null' + description: Password configuration settings for the remote access of the container volume. + required: + - algorithm + - data + properties: + algorithm: + type: string + description: The hashing algorithm used to has the password. + enum: + - raw + - sha512 + - md5 + data: + type: string + description: The raw or hashed password. + VolumeSummary: + title: VolumeSummary + type: object + description: A summary of relevant volume information. + required: + - id + - hash + - config + properties: + id: + $ref: '#/components/schemas/ID' + hash: + type: string + description: A unique hash for the given volume. + config: + $ref: '#/components/schemas/ContainerVolume' + external: + description: The ID of external volume, if applicable. + oneOf: + - type: object + properties: + id: + $ref: '#/components/schemas/ID' + - type: 'null' + removed: + description: The timestamp of the volume's removal, if applicable. + oneOf: + - $ref: '#/components/schemas/DateTime' + - type: 'null' + ContainerHighAvailabilityPrimary: + title: ContainerHighAvailabilityPrimary + description: | + Details about the instance currently elected as the high availability primary for a container. + type: object + required: + - instance_id + - priority + - elected + - last_checkin + properties: + instance_id: + description: The ID of the instance that has been elected as the primary. + $ref: '#/components/schemas/ID' + priority: + type: integer + format: int32 + description: The priority value assigned to this instance for the election. Higher priority means more likely to be elected primary. + elected: + description: The time at which this instance was elected as the primary. + $ref: '#/components/schemas/DateTime' + last_checkin: + description: The time the primary instance last checked into the high availability service. + $ref: '#/components/schemas/DateTime' + ContainerHighAvailability: + title: ContainerHighAvailability + description: | + The high availability configuration and status for a container, as determined by the platform. + type: object + required: + - last_checkin + - primary + properties: + last_checkin: + description: The last time the primary checked in. + $ref: '#/components/schemas/DateTime' + primary: + description: | + Information about the instance currently elected as the primary for this container. Null when no primary has been elected. + oneOf: + - $ref: '#/components/schemas/ContainerHighAvailabilityPrimary' + - type: 'null' + DnsRecordA: + title: DnsRecordA + type: object + description: A DNS A record. + required: + - ip + properties: + ip: + type: string + description: The IPv4 address that the A record should map to. + DnsRecordAaaa: + title: DnsRecordAaaa + type: object + description: A DNS AAAA record. + required: + - ip + properties: + ip: + type: string + description: The IPv6 address that the AAAA record should map to. + DnsRecordCname: + title: DnsRecordCname + type: object + description: A DNS CNAME record. + required: + - domain + properties: + domain: + type: string + description: The domain string the record resolves to. + DnsRecordNs: + title: DnsRecordNs + type: object + description: A DNS NS record. + required: + - domain + properties: + domain: + type: string + description: The domain of the nameserver for this record. + DnsRecordMx: + title: DnsRecordMx + type: object + description: A DNS MX record. + required: + - priority + - domain + properties: + priority: + type: integer + description: The priority setting for this mx record. + domain: + type: string + description: The domain this mx record points to. + DnsRecordTxt: + title: DnsRecordTxt + type: object + description: A DNS TXT record. + required: + - value + properties: + value: + type: string + description: The value for this TXT record. + DnsRecordAlias: + title: DnsRecordAlias + type: object + description: A DNS ALIAS record. + required: + - domain + properties: + domain: + type: string + description: The domain string returned from the DNS server when this alias record is requested. + DnsRecordSrv: + title: DnsRecordSrv + type: object + description: A DNS SRV record. + required: + - weight + - priority + - port + - domain + properties: + weight: + type: integer + description: The weight configured for this record - breaks ties for priority. + priority: + type: integer + description: The priority for the record. + port: + type: integer + description: The port number for the service. + domain: + type: string + description: The domain for the record. + DnsRecordCaa: + title: DnsRecordCaa + type: object + description: A DNS CAA record. + required: + - tag + - value + properties: + tag: + type: string + description: The ASCII string that represents the identifier of the property represented by the record. + value: + type: string + description: The value associated with the tag. + DnsRecordLinkedHttpRouting: + title: DnsRecordLinkedHttpRouting + type: object + required: + - match_path + properties: + match_path: + type: + - string + - 'null' + description: | + If set, this record will configure the load balancer to only match for paths of this domain matching this string. + If the string starts with a /, it will be a literal prefix match (/test matches /test*). Otherwise, regex is used. + DnsRecordLinkedVirtualMachine: + title: DnsRecordLinkedVirtualMachine + type: object + required: + - virtual_machine + properties: + virtual_machine: + type: object + required: + - id + - dmz + properties: + id: + $ref: '#/components/schemas/ID' + dmz: + type: boolean + description: | + If true, traffic to this domain will skip the load balancer and go directly to the virtual machine + via the gateway service. + DnsRecordLinkedDeployment: + title: DnsRecordLinkedDeployment + type: object + properties: + deployment: + type: object + description: Information about the deployment this record points to. + required: + - environment_id + - match + properties: + environment_id: + $ref: '#/components/schemas/ID' + description: The ID of the environment with the deployment tag mapping we want to reference. + match: + type: object + description: Describes which container and which tagged deployment this record should target. + required: + - container + properties: + container: + $ref: '#/components/schemas/Identifier' + description: The identifier of the container in the environment this record should point to. + tag: + description: The deployment tag that this record should point to. The tags are set on the root of an environment and map to a deployment version. + anyOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + DnsRecordLinkedVariantDestination: + title: DnsRecordLinkedVariantDestination + description: The destination a variant routes traffic to. + oneOf: + - type: object + properties: + container_id: + type: string + description: The ID of the container this record is related to. + - $ref: '#/components/schemas/DnsRecordLinkedVirtualMachine' + - $ref: '#/components/schemas/DnsRecordLinkedDeployment' + DnsRecordLinkedVariant: + title: DnsRecordLinkedVariant + type: object + description: A weighted routing variant. Traffic is distributed across variants according to their weights. + required: + - destination + - weight + properties: + destination: + $ref: '#/components/schemas/DnsRecordLinkedVariantDestination' + weight: + type: integer + minimum: 0 + maximum: 1000 + description: The weight of this variant relative to the other variants, used to distribute traffic across destinations. Valid range is 0 to 1000. + DnsRecordLinkedRouting: + title: DnsRecordLinkedRouting + type: object + description: Rules for routing traffic at the load balancer for this linked record. + properties: + http: + oneOf: + - $ref: '#/components/schemas/DnsRecordLinkedHttpRouting' + - type: 'null' + variants: + type: + - array + - 'null' + description: A set of weighted destinations that traffic to this record is distributed across. + items: + $ref: '#/components/schemas/DnsRecordLinkedVariant' + DnsRecordLinked: + title: DnsRecordLINKED + type: object + description: A LINKED record is a record special to Cycle. It represents a URL that points to a specific container or deployment of a container, however the IP address mapping is handled automatically by the platform. + allOf: + - type: object + required: + - features + - routing + properties: + routing: + $ref: '#/components/schemas/DnsRecordLinkedRouting' + features: + type: object + description: Features associated with this record. + required: + - tls + - geodns + properties: + tls: + type: object + description: TLS properties of the record. + required: + - enable + properties: + enable: + type: boolean + description: A boolean, where true represents this record will be paired with a TLS certificate automatically maintained by the platform. + geodns: + type: object + description: Options for the GeoDNS LINKED record feature. + required: + - enable + properties: + enable: + type: boolean + description: If enabled, Cycle will attempt to match inbound requests to the closest load balancer geographically. + wildcard: + type: + - object + - 'null' + required: + - resolve_sub_domains + properties: + resolve_sub_domains: + description: If enabled, subdomains will resolve for wildcard records. If disabled, only the primary domain will resolve. + default: false + type: boolean + - oneOf: + - type: object + properties: + container_id: + type: string + description: The ID of the container this record is related to. + - $ref: '#/components/schemas/DnsRecordLinkedVirtualMachine' + - $ref: '#/components/schemas/DnsRecordLinkedDeployment' + DnsRecordTypes: + title: DnsRecordTypes + type: object + description: DNS record types the platform supports. + properties: + a: + $ref: '#/components/schemas/DnsRecordA' + aaaa: + $ref: '#/components/schemas/DnsRecordAaaa' + cname: + $ref: '#/components/schemas/DnsRecordCname' + ns: + $ref: '#/components/schemas/DnsRecordNs' + mx: + $ref: '#/components/schemas/DnsRecordMx' + txt: + $ref: '#/components/schemas/DnsRecordTxt' + alias: + $ref: '#/components/schemas/DnsRecordAlias' + srv: + $ref: '#/components/schemas/DnsRecordSrv' + caa: + $ref: '#/components/schemas/DnsRecordCaa' + linked: + $ref: '#/components/schemas/DnsRecordLinked' + DnsRecordTlsCertificate: + title: DnsRecordTlsCertificate + type: object + description: A TLS certificate assigned to a DNS record. + required: + - id + - generated + - wildcard_child + - user_supplied + properties: + id: + $ref: '#/components/schemas/ID' + generated: + $ref: '#/components/schemas/DateTime' + wildcard_child: + type: boolean + description: A value where true represents that the certificate is using a shared wildcard cert. + user_supplied: + type: boolean + description: If true, this certificate was manually supplied, and was not auto-generated by the platform. + expires: + $ref: '#/components/schemas/DateTime' + description: The time that this certificate expires. + DnsRecordState: + title: DnsRecordState + allOf: + - required: + - current + properties: + current: + description: The current state of the record. + type: string + enum: + - pending + - live + - deleting + - deleted + - $ref: '#/components/schemas/State' + Events: + title: Events + description: Describes the date and time at which certain events occurred in the lifetime of this resource. + type: object + additionalProperties: + $ref: '#/components/schemas/DateTime' + DnsRecord: + title: DnsRecord + type: object + description: A DNS record. + required: + - id + - hub_id + - creator + - zone_id + - name + - resolved_domain + - type + - features + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + hub_id: + $ref: '#/components/schemas/HubID' + creator: + $ref: '#/components/schemas/CreatorScope' + zone_id: + type: string + description: A unique identifier for the zone + name: + type: string + description: A name used for the record, where `@` signifies the use of the root domain. + resolved_domain: + type: string + description: The name of the record and the origin as a domain name. + type: + $ref: '#/components/schemas/DnsRecordTypes' + features: + description: TLS features for the record. + oneOf: + - type: object + required: + - certificate + properties: + certificate: + anyOf: + - $ref: '#/components/schemas/DnsRecordTlsCertificate' + - type: 'null' + - type: 'null' + state: + $ref: '#/components/schemas/DnsRecordState' + events: + $ref: '#/components/schemas/Events' + IpOptions: + title: IpOptions + type: object + description: Options for an IP. + properties: + proxy_arp: + description: If enabled, allows pool to respond to ARP requests, on behalf of a container / virtual machine, at the host level. + oneOf: + - type: boolean + - type: 'null' + IpState: + title: IpState + allOf: + - required: + - current + properties: + current: + description: The current state of the IP. + type: string + enum: + - assigning + - assigned + - releasing + - available + - $ref: '#/components/schemas/State' + Ip: + title: IP + type: object + description: Details about an IP. + required: + - id + - hub_id + - kind + - ip + - assignment + - pool_id + - network_id + - address + - gateway + - cidr + - state + properties: + id: + $ref: '#/components/schemas/ID' + hub_id: + $ref: '#/components/schemas/HubID' + kind: + type: string + description: The type of IP protocol this IP is. + enum: + - ipv4 + - ipv6 + ip: + description: The IP string this IP represents. + $ref: '#/components/schemas/IpAddress' + assignment: + description: Information about the assignment of this IP. + oneOf: + - type: object + required: + - container_id + - instance_id + - environment_id + properties: + container_id: + $ref: '#/components/schemas/ID' + instance_id: + $ref: '#/components/schemas/ID' + environment_id: + $ref: '#/components/schemas/ID' + virtual_machine: + type: object + description: Details about the virtual machine this IP is assigned to. + properties: + id: + $ref: '#/components/schemas/ID' + required: + - id + - type: 'null' + pool_id: + $ref: '#/components/schemas/ID' + description: A unique identifier that associates the IP with an IP pool. + network_id: + $ref: '#/components/schemas/ID' + description: A unique identifier that associates the IP with a network. + address: + type: string + description: The IP address. + gateway: + type: string + description: The IP gateway. + network: + oneOf: + - $ref: '#/components/schemas/Cidr' + - type: 'null' + options: + oneOf: + - $ref: '#/components/schemas/IpOptions' + - type: 'null' + cidr: + type: string + description: The CIDR for the IP. + state: + $ref: '#/components/schemas/IpState' + ContainersMeta: + title: ContainersMeta + type: object + description: A list of meta fields that can be applied to a container. + properties: + instances_count: + $ref: '#/components/schemas/StateCountSummary' + domains: + type: + - array + - 'null' + items: + type: object + description: Any associated Linked Records for this container, and their fully-qualified domain name (fqdn). + required: + - fqdn + properties: + fqdn: + type: string + description: The fully qualified domain name. + record: + $ref: '#/components/schemas/DnsRecord' + ips: + description: An array of IP resources. + type: array + items: + $ref: '#/components/schemas/Ip' + Container: + title: Container + type: object + description: Containers are a way to package together your application along with it's dependencies, and run in a resource isolated process. They provide consistency across different hosts, efficiency over traditional hosting methods, and facilitate a micro-service based approach, where each logical piece of your application is split into multiple, easily testable parts (such as API, Backend, Frontend, etc). + required: + - id + - name + - identifier + - creator + - environment + - hub_id + - image + - config + - instances + - stateful + - state + - role + - ha + - deployment + - deprecate + - lock + - events + properties: + id: + $ref: '#/components/schemas/ID' + identifier: + $ref: '#/components/schemas/Identifier' + description: A human readable slugged identifier for this container. Usually used as a key in a stack file. + name: + type: string + description: A user defined name for the container resource. + creator: + $ref: '#/components/schemas/CreatorScope' + environment: + $ref: '#/components/schemas/ContainerEnvironmentSummary' + hub_id: + $ref: '#/components/schemas/HubID' + image: + $ref: '#/components/schemas/ImageSummary' + stack: + anyOf: + - $ref: '#/components/schemas/StackSummary' + - type: 'null' + config: + $ref: '#/components/schemas/Config' + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + instances: + type: integer + description: The number of instances for a given container. + volumes: + type: array + items: + $ref: '#/components/schemas/VolumeSummary' + annotations: + description: Custom meta data for a given container + oneOf: + - type: object + additionalProperties: {} + - type: 'null' + role: + description: The role of a given container if it has one. + oneOf: + - type: string + enum: + - orchestrator + - type: 'null' + ha_elections: + description: High availability election status of the container. Contains information about the primary instance, if any. + oneOf: + - $ref: '#/components/schemas/ContainerHighAvailability' + - type: 'null' + stateful: + type: boolean + description: A boolean where true signifies the container is stateful. + deprecate: + type: boolean + description: A boolean where true signifies the container is marked as deprecated. + lock: + type: boolean + description: When set to true, prevents this container from being deleted. + state: + $ref: '#/components/schemas/ContainerState' + events: + title: ContainerEvents + type: object + description: A collection of timestamps for each event in the container's lifetime. + required: + - created + - updated + - deleted + - started + properties: + created: + description: The timestamp of when the container was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the container was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the container was deleted. + $ref: '#/components/schemas/DateTime' + started: + description: The timestamp of when the container was started. + $ref: '#/components/schemas/DateTime' + meta: + $ref: '#/components/schemas/ContainersMeta' + EnvironmentNetworkSummary: + title: EnvironmentNetworkSummary + type: object + description: Details about the environment network this instance is a member of. + required: + - id + - network_subnet + - subnet + - ipv6 + - legacy + - mac_addr + - vxlan_tag + properties: + id: + $ref: '#/components/schemas/ID' + network_subnet: + type: string + subnet: + type: string + ipv6: + anyOf: + - $ref: '#/components/schemas/IPNet' + - type: 'null' + legacy: + oneOf: + - type: object + required: + - host + - subnet + - ipv4 + properties: + host: + type: integer + subnet: + type: integer + ipv4: + anyOf: + - $ref: '#/components/schemas/IPNet' + - type: 'null' + - type: 'null' + mac_addr: + type: string + vxlan_tag: + type: integer + InstanceProvider: + title: InstanceProvider + type: object + required: + - vendor + - integration_id + - location + properties: + vendor: + type: string + description: The vendor of the hub provider integration related to the server this instance runs on. + integration_id: + $ref: '#/components/schemas/ID' + description: An ID of the provider Hub integration that this instance's host node is related to. + location: + type: string + description: The identifier of the location related to the server this instance runs on. + InstanceState: + title: InstanceState + description: Information about the state of an instance. + allOf: + - required: + - current + properties: + current: + description: The current state of the instance. + type: string + enum: + - new + - starting + - migrating + - running + - stopping + - stopped + - failed + - deleting + - deleted + health: + description: information about the health of the instance. + oneOf: + - type: object + required: + - healthy + - updated + properties: + healthy: + description: | + Describes the healthiness of the instance. Health checks can be configured at the container level. + - `true`: The instance is considered healthy. + - `false`: The instance is considered unhealthy. + - `null`: The instance has not yet reported its health, or a health check has not yet been performed. + oneOf: + - type: boolean + - type: 'null' + updated: + description: A timestamp of the last time the instance health was updated. + $ref: '#/components/schemas/DateTime' + - type: 'null' + readiness: + description: information about the readiness of the instance. + oneOf: + - type: object + required: + - ready + - updated + properties: + ready: + description: | + Describes the readiness of the instance. + - `true`: The instance is ready. + - `false`: The instance is not ready. + - `null`: The instance has not yet reported its readiness, or a readiness check has not yet been performed. + oneOf: + - type: boolean + - type: 'null' + updated: + description: A timestamp of the last time the instance readiness was updated. + $ref: '#/components/schemas/DateTime' + - type: 'null' + - $ref: '#/components/schemas/State' + InstanceAutoScale: + title: InstanceAutoScale + description: Auto-scale details for instances created by auto-scale events. + type: object + required: + - min_ttl + properties: + min_ttl: + $ref: '#/components/schemas/DateTime' + InstanceTrafficDrain: + title: InstanceTrafficDrain + description: Traffic drain details for instance. + type: object + required: + - started + properties: + started: + $ref: '#/components/schemas/DateTime' + MigrationInstance: + title: MigrationInstance + type: object + description: Information about a migrated instance. + required: + - instance_id + - server_id + properties: + instance_id: + type: string + description: The ID of the instance. + server_id: + type: string + description: The ID of the server. + InstanceMigration: + title: InstanceMigration + type: object + description: Information regarding the migration of an instance, such as the server that the instance came from or the server that the instance was moved to. + required: + - key + - copy_volumes + properties: + to: + anyOf: + - $ref: '#/components/schemas/MigrationInstance' + - type: 'null' + from: + anyOf: + - $ref: '#/components/schemas/MigrationInstance' + - type: 'null' + started: + description: A timestamp of when the migration was started. + $ref: '#/components/schemas/DateTime' + completed: + description: A timestamp of when the migration was completed. + $ref: '#/components/schemas/DateTime' + key: + type: string + description: A key used by the platform to verify the migration. + copy_volumes: + type: boolean + description: A boolean where true represents the volumes for the instance should be copied to the new server as well. + InstanceHighAvailability: + title: InstanceHighAvailability + description: | + The high availability status of the instance, as determined by the platform. + + This data becomes avaialble when utilizing the internal API high availability endpoint. The platform will hold elections for all instances hitting the endpoint and choose a primary. As long as those instances continue to check in, the primary will continue to be the primary until it is dropped off. After which, a secondary will be promoted. + type: object + required: + - last_checkin + properties: + elected_primary: + description: If a time is set, indicates that this instance is the primary, and the time at which it was promoted. + oneOf: + - $ref: '#/components/schemas/DateTime' + - type: 'null' + last_checkin: + description: The time that the instance last checked into the HA service. + $ref: '#/components/schemas/DateTime' + NodeState: + title: NodeState + allOf: + - required: + - current + - changed + properties: + current: + description: The current state of the node. + type: string + enum: + - new + - offline + - authorizing + - online + - decommissioned + - deleted + changed: + $ref: '#/components/schemas/DateTime' + desired: + oneOf: + - type: string + enum: + - new + - offline + - authorizing + - online + - decommissioned + - deleted + - type: 'null' + - $ref: '#/components/schemas/State' + InstanceMeta: + title: InstanceMeta + type: object + description: A list of meta fields that can be applied to an instance. + properties: + node: + type: object + properties: + healthy: + type: boolean + online: + type: boolean + last_checkin: + $ref: '#/components/schemas/DateTime' + state: + $ref: '#/components/schemas/NodeState' + sdn_pool_ips: + type: array + items: + $ref: '#/components/schemas/Ip' + Instance: + title: Instance + type: object + description: An instance of a Container. + required: + - id + - creator + - hub_id + - container_id + - location_id + - environment + - provider + - server_id + - ready_state + - hostname + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + creator: + $ref: '#/components/schemas/CreatorScope' + hub_id: + $ref: '#/components/schemas/HubID' + container_id: + type: string + description: A container identifier for the container that is associated with this instance. + location_id: + type: string + description: A location identifier that's associated with the server this instance is deployed to. + environment: + $ref: '#/components/schemas/EnvironmentNetworkSummary' + stateful: + description: If the instance is stateful, additional details relating to its stateful properties. + oneOf: + - type: object + required: + - id + - base_hostname + properties: + id: + $ref: '#/components/schemas/ID' + base_hostname: + type: string + description: The base hostname for the given instance. + - type: 'null' + function: + type: object + description: If the instance is a function, additional details relating to its function properties + required: + - seed + properties: + seed: + type: integer + description: The seed used for this function. + provider: + $ref: '#/components/schemas/InstanceProvider' + server_id: + $ref: '#/components/schemas/ID' + description: An identifier for the server this instance is deployed to. + ready_state: + type: string + description: The state as it relates to the following. * `active` - instance can be started or stopped. * `purge` - instance should be deleted. * `hibernate` - instance is active but not allowed to run. * `configuring` - this instance is not allowed to start yet + enum: + - active + - purge + - hibernate + - configuring + purge_time: + description: The timestamp of when the instance was purged. + anyOf: + - $ref: '#/components/schemas/DateTime' + - type: 'null' + hostname: + type: string + description: The hostname of the instance. + service: + $ref: '#/components/schemas/ServiceContainerIdentifier' + description: The type of service this instance is within the environment, if any. + extension: + anyOf: + - $ref: '#/components/schemas/ContainerExtension' + - type: 'null' + state: + $ref: '#/components/schemas/InstanceState' + autoscale: + anyOf: + - $ref: '#/components/schemas/InstanceAutoScale' + - type: 'null' + traffic_drain: + anyOf: + - $ref: '#/components/schemas/InstanceTrafficDrain' + - type: 'null' + migration: + anyOf: + - $ref: '#/components/schemas/InstanceMigration' + - type: 'null' + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + ha_elections: + oneOf: + - $ref: '#/components/schemas/InstanceHighAvailability' + - type: 'null' + events: + title: InstanceEvents + description: A collection of timestamps for each event in the instance's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the instance was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the instance was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the instance was deleted. + $ref: '#/components/schemas/DateTime' + meta: + anyOf: + - $ref: '#/components/schemas/InstanceMeta' + - type: 'null' + ContainerSummary: + title: ContainerSummary + type: object + description: A summary of a Container. + required: + - id + - name + - creator + - environment + - hub_id + - image + - state + - deprecate + - lock + - events + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: A user defined name for the Container resource. + creator: + $ref: '#/components/schemas/CreatorScope' + environment: + $ref: '#/components/schemas/ContainerEnvironmentSummary' + hub_id: + $ref: '#/components/schemas/HubID' + stack: + anyOf: + - $ref: '#/components/schemas/StackSummary' + - type: 'null' + image: + $ref: '#/components/schemas/ImageSummary' + annotations: + description: Custom meta data for a given Container. Not utilized by the platform. + oneOf: + - type: object + additionalProperties: {} + - type: 'null' + state: + $ref: '#/components/schemas/ContainerState' + ha_elections: + description: High availability elections status of the container. Contains information about the primary instance, if any. + oneOf: + - $ref: '#/components/schemas/ContainerHighAvailability' + - type: 'null' + role: + type: + - string + - 'null' + description: The role of a given Container if it has one. + enum: + - contductor + deprecate: + type: boolean + description: A boolean where true signifies the Container is marked as deprecated. + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + lock: + type: boolean + description: When set to true, prevents this Container from being deleted. + events: + title: ContainerEvents + type: object + description: A collection of timestamps for each event in the Container's lifetime. + required: + - created + - updated + - deleted + - started + properties: + created: + description: The timestamp of when the Container was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the Container was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the Container was deleted. + $ref: '#/components/schemas/DateTime' + started: + description: The timestamp of when the Container was started. + $ref: '#/components/schemas/DateTime' + InstanceSummary: + title: InstanceSummary + type: object + description: A summary of an instance of a Container. + required: + - id + - creator + - hub_id + - container_id + - location_id + - environment + - provider + - server_id + - ready_state + - hostname + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + creator: + $ref: '#/components/schemas/CreatorScope' + hub_id: + $ref: '#/components/schemas/HubID' + container_id: + type: string + description: A container identifier for the container that is associated with this instance. + location_id: + type: string + description: A location identifier that's associated with the server this instance is deployed to. + environment: + $ref: '#/components/schemas/EnvironmentNetworkSummary' + stateful: + description: If the instance is stateful, additional details relating to its stateful properties. + oneOf: + - type: object + required: + - id + - base_hostname + properties: + id: + $ref: '#/components/schemas/ID' + base_hostname: + type: string + description: The base hostname for the given instance. + - type: 'null' + autoscale: + anyOf: + - $ref: '#/components/schemas/InstanceAutoScale' + - type: 'null' + provider: + $ref: '#/components/schemas/InstanceProvider' + server_id: + $ref: '#/components/schemas/ID' + description: An identifier for the server this instance is deployed to. + ready_state: + type: string + description: | + The state as it relates to the following: + - `active` - instance can be started or stopped. + - `purge` - instance should be deleted. + - `hibernate` - instance is active but not allowed to run. + - `configuring` - this instance is not allowed to start yet + enum: + - active + - purge + - hibernate + - configuring + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + hostname: + type: string + description: The hostname of the instance. + service: + $ref: '#/components/schemas/ServiceContainerIdentifier' + description: The type of service this instance is within the environment, if any. + state: + $ref: '#/components/schemas/InstanceState' + ServiceContainer: + title: ServiceContainer + description: Details about a service container and its instances. + type: object + required: + - container + properties: + container: + $ref: '#/components/schemas/ContainerSummary' + instances: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/InstanceSummary' + VirtualMachineNetworkConfig: + title: VirtualMachineNetworkConfig + type: object + description: | + Defines the network settings for a virtual machine, including public access mode, hostname, and ports. + required: + - public + - hostname + - egress_via_gateway + properties: + public: + type: string + enum: + - enable + - disable + - egress-only + - environment-limited + description: Controls the public network mode for the virtual machine. + hostname: + type: string + description: The hostname assigned to the virtual machine. + ports: + anyOf: + - type: array + items: + type: string + - type: 'null' + description: Port configurations for the virtual machine. + egress_via_gateway: + description: True indicates that traffic should leave via the gateway, not the underlying host. + type: boolean + VirtualMachineDeployTags: + title: VirtualMachineDeployTags + type: object + description: | + Tags that define node requirements for the deployment. The `any` tag must match at least one condition, while `all` must match all conditions. + properties: + any: + anyOf: + - type: array + items: + type: string + - type: 'null' + all: + anyOf: + - type: array + items: + type: string + - type: 'null' + VirtualMachineNodeConstraints: + title: VirtualMachineNodeConstraints + type: object + description: | + Node-level constraints for the virtual machine deployment, specifying tags that must or must not be present. + properties: + tags: + $ref: '#/components/schemas/VirtualMachineDeployTags' + required: + - tags + VirtualMachineDeployConstraints: + title: VirtualMachineDeployConstraints + type: object + description: | + Constraints define node-level and resource restrictions for the virtual machine deployment. + properties: + node: + anyOf: + - $ref: '#/components/schemas/VirtualMachineNodeConstraints' + - type: 'null' + secrets: + anyOf: + - type: array + items: + type: string + - type: 'null' + containers: + anyOf: + - type: array + items: + type: string + - type: 'null' + VirtualMachineShutdownPolicy: + title: VirtualMachineShutdownPolicy + type: object + description: | + The shutdown policy defines how the virtual machine should handle shutdown, including a timeout and signals to be sent during shutdown. + properties: + graceful_timeout: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: The timeout period for graceful shutdown. + VirtualMachineStartupPolicy: + title: VirtualMachineStartupPolicy + type: object + description: | + The startup policy defines how the virtual machine should handle startup, including a possible delay before starting the machine. + properties: + delay: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: Delay before startup. + VirtualMachineTelemetryConfig: + title: VirtualMachineTelemetryConfig + type: object + description: | + The telemetry configuration defines how telemetry data is handled, including retention, interval, and whether telemetry is disabled. + properties: + retention: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: Data retention duration for telemetry. + interval: + anyOf: + - $ref: '#/components/schemas/Duration' + - type: 'null' + description: Telemetry collection interval. + disable: + type: boolean + description: Whether telemetry collection is disabled. + required: + - disable + VirtualMachineDeployConfig: + title: VirtualMachineDeployConfig + type: object + description: | + Represents the deployment configuration for a virtual machine, including constraints, shutdown/startup policies, restart conditions, and telemetry settings. + properties: + constraints: + anyOf: + - $ref: '#/components/schemas/VirtualMachineDeployConstraints' + - type: 'null' + shutdown: + anyOf: + - $ref: '#/components/schemas/VirtualMachineShutdownPolicy' + - type: 'null' + startup: + anyOf: + - $ref: '#/components/schemas/VirtualMachineStartupPolicy' + - type: 'null' + telemetry: + anyOf: + - $ref: '#/components/schemas/VirtualMachineTelemetryConfig' + - type: 'null' + VirtualMachineRamResources: + title: VirtualMachineRamResources + type: object + description: | + Defines the RAM configuration of a virtual machine. + properties: + limit: + type: string + description: The limit (maximum) amount of RAM the virtual machine can consume. Must be at least 512M and less than 65GB. + examples: + - 1G + - 512M + allocate: + type: + - boolean + - 'null' + description: Whether or not the RAM set in limit should be preallocated. + required: + - limit + VirtualMachineCpuResources: + title: VirtualMachineCpuResources + type: object + description: | + Defines the CPU configuration of a virtual machine. Set **either** `cores` or `cpus`. + properties: + cores: + anyOf: + - type: object + properties: + number: + type: integer + description: The number of cores to assign to this virtual machine. Must be between 1 and 32. + examples: + - 1 + - 2 + allocate: + type: + - boolean + - 'null' + description: If true, reserves the cores so they cannot be used by any other virtual machine. + required: + - number + - type: 'null' + cpus: + type: + - string + - 'null' + description: The specific cores/range of cores to allocate to the virtual machine. An 'x' indicates the maximum core for a given machine. + examples: + - '1' + - 1-3 + - 2-x + VirtualMachineResourcesConfig: + title: VirtualMachineResourcesConfig + type: object + description: | + Defines the resource settings for a virtual machine, including CPU and RAM. + properties: + ram: + $ref: '#/components/schemas/VirtualMachineRamResources' + cpu: + $ref: '#/components/schemas/VirtualMachineCpuResources' + required: + - ram + - cpu + VirtualMachineCpuConfigDefault: + title: VirtualMachineCpuConfigDefault + type: object + description: Predefined CPU selection. + required: + - type + - details + properties: + type: + type: string + enum: + - host + - qemu32 + - qemu64 + - kvm64 + description: Predefined CPU type. + details: + type: object + description: An object with no properties. + properties: {} + additionalProperties: false + VirtualMachineCpuConfigCustom: + title: VirtualMachineCpuConfigCustom + type: object + description: Custom CPU selection with model and feature flags. + required: + - type + - details + properties: + type: + type: string + enum: + - custom + description: Custom CPU definition. + details: + type: object + required: + - model + properties: + model: + type: string + description: CPU model string (for example "Skylake-Client"). + feature_flags: + oneOf: + - type: array + description: Additional CPU feature flags to enable. Will start with a "+" or "-" to include or exclude. + example: + - +avx + - '-vmz' + items: + type: string + - type: 'null' + VirtualMachineRuntimeConfigHardware: + title: VirtualMachineRuntimeConfigHardware + type: object + description: | + Hardware parameters applied for VM runtime. + required: + - cpu + properties: + machine_type: + description: QEMU machine type to emulate. + oneOf: + - type: string + enum: + - pc + - q35 + - microvm + - type: 'null' + cpu: + description: CPU configuration for the VM. Discriminated by `type`. + oneOf: + - $ref: '#/components/schemas/VirtualMachineCpuConfigDefault' + - $ref: '#/components/schemas/VirtualMachineCpuConfigCustom' + discriminator: + propertyName: type + mapping: + host: '#/components/schemas/VirtualMachineCpuConfigDefault' + qemu32: '#/components/schemas/VirtualMachineCpuConfigDefault' + qemu64: '#/components/schemas/VirtualMachineCpuConfigDefault' + kvm64: '#/components/schemas/VirtualMachineCpuConfigDefault' + custom: '#/components/schemas/VirtualMachineCpuConfigCustom' + additionalProperties: false + VirtualMachineAttachmentTypeIso: + title: VirtualMachineAttachmentTypeIso + type: object + description: Details of an ISO attachment for a virtual machine. + required: + - type + - details + properties: + type: + type: string + enum: + - iso + description: The type of the attachment (iso) + details: + type: object + required: + - url + properties: + url: + type: string + description: The URL of the ISO to download and attach to this virtual machine. + VirtualMachineRuntimeConfigAttachment: + title: VirtualMachineRuntimeConfigAttachment + description: | + Additional attachment (ISO, etc) added during runtime. + oneOf: + - $ref: '#/components/schemas/VirtualMachineAttachmentTypeIso' + discriminator: + propertyName: type + mapping: + iso: '#/components/schemas/VirtualMachineAttachmentTypeIso' + VirtualMachineRuntimeConfig: + title: VirtualMachineRuntimeConfig + type: object + description: | + Defines the runtime settings for a virtual machine. + properties: + hardware: + description: Hardware parameters applied for VM runtime. + oneOf: + - $ref: '#/components/schemas/VirtualMachineRuntimeConfigHardware' + - type: 'null' + attach: + description: An array of attachments to 'plug in' to the virtual machine. + oneOf: + - type: array + items: + $ref: '#/components/schemas/VirtualMachineRuntimeConfigAttachment' + - type: 'null' + os_flavor: + description: The type of operating system that will be installed to the virtual machine. Allows for preconfigured settings, such as virtio-win drivers for Windows. + oneOf: + - type: string + enum: + - linux + - unix + - windows + additionalProperties: false + VirtualMachineConfig: + title: VirtualMachineConfig + type: object + description: | + Defines the network and deployment configurations for a virtual machine. + properties: + network: + $ref: '#/components/schemas/VirtualMachineNetworkConfig' + deploy: + $ref: '#/components/schemas/VirtualMachineDeployConfig' + resources: + $ref: '#/components/schemas/VirtualMachineResourcesConfig' + runtime: + oneOf: + - $ref: '#/components/schemas/VirtualMachineRuntimeConfig' + - type: 'null' + required: + - network + - deploy + - resources + VirtualMachineImageSourceUrl: + title: VirtualMachineImageSourceUrl + description: A virtual machine image sourced from a URL. + type: object + properties: + type: + type: string + enum: + - url + details: + type: object + properties: + url: + type: string + description: The URL where a custom image is located. + required: + - url + required: + - type + - details + VirtualMachineImageSourceIpxe: + title: VirtualMachineImageSourceIpxe + description: A virtual machine image sourced from an IPXE script. + type: object + properties: + type: + type: string + enum: + - ipxe + details: + type: object + properties: + chain_url: + type: + - string + - 'null' + description: A URL that points to an IPXE script. + script: + type: + - string + - 'null' + description: An inline IPXE script. + required: + - type + - details + VirtualMachineImageSourceBase: + title: VirtualMachineImageSourceBase + description: A virtual machine image sourced from a Cycle base image. + type: object + properties: + type: + type: string + enum: + - base + details: + type: object + properties: + identifier: + type: string + description: The base image identifier. + required: + - identifier + required: + - type + - details + VirtualMachineImageSourceExternalVolume: + title: VirtualMachineImageSourceExternalVolume + description: A virtual machine image sourced from a SAN target. + type: object + required: + - type + - details + properties: + type: + type: string + enum: + - external-volume + details: + type: object + properties: + identifier: + description: The identifier of the external volume where the image is located. + oneOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + id: + description: The id of the external volume where the image is located. + oneOf: + - $ref: '#/components/schemas/ID' + - type: 'null' + VirtualMachineImage: + title: VirtualMachineImage + type: object + description: | + Represents the image used by a virtual machine. It can either reference a URL where the image is located or specify a base image provided by Cycle. + discriminator: + propertyName: type + mapping: + url: '#/components/schemas/VirtualMachineImageSourceUrl' + ipxe: '#/components/schemas/VirtualMachineImageSourceIpxe' + base: '#/components/schemas/VirtualMachineImageSourceBase' + external-volume: '#/components/schemas/VirtualMachineImageSourceExternalVolume' + oneOf: + - $ref: '#/components/schemas/VirtualMachineImageSourceUrl' + - $ref: '#/components/schemas/VirtualMachineImageSourceIpxe' + - $ref: '#/components/schemas/VirtualMachineImageSourceBase' + - $ref: '#/components/schemas/VirtualMachineImageSourceExternalVolume' + VirtualMachineVolumeConfig: + title: VirtualMachineVolumeConfig + type: object + description: | + Represents the configuration for a volume attached to a virtual machine. + required: + - identifier + - read_only + properties: + local: + anyOf: + - type: object + required: + - max_size + properties: + max_size: + type: string + description: The maximum size allowed for the local volume. + examples: + - 100G + storage_pool: + anyOf: + - type: boolean + - type: 'null' + description: Indicates if the volume is part of a storage pool. + stateless: + type: + - boolean + - 'null' + default: false + description: | + If set to true, this volume will be treated as ephemeral. Stateless volumes will **NOT** be migrated. + Base volumes cannot be stateless. + - type: 'null' + description: Configuration details for a local volume. + external: + anyOf: + - type: object + properties: + id: + oneOf: + - $ref: '#/components/schemas/ID' + - type: 'null' + description: The id of the external volume. + - type: 'null' + description: Configuration details for a SAN volume. + identifier: + $ref: '#/components/schemas/Identifier' + read_only: + type: boolean + description: Specifies if the volume is mounted as read-only. + VirtualMachineVolume: + title: VirtualMachineVolume + type: object + description: | + Represents a storage volume attached to a virtual machine. + properties: + id: + $ref: '#/components/schemas/ID' + hash: + type: string + description: A unique hash identifying the volume for the virtual machine. + config: + $ref: '#/components/schemas/VirtualMachineVolumeConfig' + description: The configuration details for the virtual machine's volume. + removed: + description: The timestamp of the volume's removal, if applicable. + oneOf: + - $ref: '#/components/schemas/DateTime' + - type: 'null' + required: + - id + - hash + - config + VirtualMachineState: + title: VirtualMachineState + allOf: + - required: + - current + properties: + current: + description: The current state of the virtual machine. + type: string + enum: + - new + - starting + - configuring + - running + - stopping + - stopped + - deleting + - deleted + - $ref: '#/components/schemas/State' + ServerSharedFileSystems: + title: ServerSharedFileSystems + type: object + properties: + mounts: + oneOf: + - type: object + additionalProperties: + type: object + required: + - type + - options + - source + properties: + type: + type: string + description: String describing the server mount type. + options: + type: string + description: Comma separated string describing the server mount options. + examples: + - key1=value1,key2=value2 + source: + type: string + description: String describing the server mount source. + - type: 'null' + directories: + description: An object describing directory identifiers with value {}. + oneOf: + - type: object + additionalProperties: {} + - type: 'null' + ServerProvider: + title: ServerProvider + type: object + description: A resource regarding the provider a given server is deployed from. + required: + - vendor + - integration_id + - model + - location + - server + properties: + vendor: + type: string + description: The vendor for the provider this server is deployed from. + integration_id: + $ref: '#/components/schemas/ID' + model: + type: string + description: The model of the server that is deployed. + zone: + type: + - string + - 'null' + description: The zone of the server that is deployed, if defined. + location: + type: string + description: A location where the server is deployed. + server: + type: string + description: A provider specific identifier for the server. + init_ips: + description: The IP's assigned to this server during provisioning. + type: array + items: + type: string + mac_addr: + type: string + description: The mac address for the server. + extra: + type: object + additionalProperties: true + provision_options: + type: object + properties: + encrypt_storage: + type: boolean + storage_size: + type: number + reservation_id: + type: string + ServerFeatures: + title: ServerFeatures + type: object + description: A set of features a given server can have and their information. + required: + - sftp + properties: + sftp: + type: boolean + description: A boolean where true means the server accepts incoming SFTP connections through the remote volume integration. + base_volume_gb: + type: + - integer + - 'null' + description: The size of the base volume (where Cycle stores container images on this server). + gateway: + description: Configuration options for running gateway services on this server. + oneOf: + - type: object + required: + - type + properties: + type: + type: string + description: The type of gateway service that can be run on this server. + enum: + - bgp + - static + - type: 'null' + ServerConstraints: + title: ServerConstraints + type: object + description: Constraints to apply to the server. + required: + - tags + - allow + properties: + tags: + description: A list of server tags to put on the given server. + type: array + items: + type: string + allow: + type: object + description: Settings for the server, things that are or are not allowed. + required: + - pool + - services + - overcommit + properties: + pool: + type: boolean + description: A boolean where true means - allow containers with no tags specified to be deployed to this server. + services: + type: boolean + description: A boolean where true means - allow service containers to be deployed to this container. + overcommit: + type: boolean + description: A boolean where true means - allow twice the normal amount of CPU shares to be allocated to containers deployed to this server. + overcommit_multiple: + type: + - integer + - 'null' + description: An integer that describes the capability of a server to overcommit shares. This will allow more containers to run on a given server based on the servers available CPU. 1 thread (or vCPU) = 10 shares. + ServerState: + title: ServerState + allOf: + - required: + - current + properties: + current: + description: The current state of the server. + type: string + enum: + - new + - provisioning + - configuring + - quarantined + - live + - deleting + - deleted + - $ref: '#/components/schemas/State' + ServerStatsNetwork: + title: ServerStatsNetwork + type: object + description: Statistics about the networks on a given server. + required: + - external_ipv4 + - external_ipv6 + properties: + interfaces: + type: object + description: Network interfaces for a given server. + additionalProperties: + type: object + required: + - interface + - flags + - mtu + - mac_addr + - speed + - rx_bytes + - tx_bytes + description: Network interface. + properties: + interface: + type: string + description: The interface name. + flags: + type: string + description: Flags for the given interface. + mtu: + type: integer + description: The maximum transmission unit for the interface. + mac_addr: + type: string + description: The mac address for the interface. + addrs: + description: An array of IP addresses associated with the interface. + type: + - array + - 'null' + items: + type: string + speed: + description: The link speed for the interface in megabits. + type: integer + rx_bytes: + description: The bytes received over the interface. + type: integer + tx_bytes: + description: The bytes transmitted over the interface. + type: integer + external_ipv4: + type: string + description: The public IPv4 address used to connect to this server. + external_ipv6: + type: string + description: The public IPv6 address used to connect to this server. + ServerStatsUptime: + title: ServerStatsUptime + type: object + description: Statistics describing the uptime of a given server. + properties: + seconds: + type: number + description: The amount in seconds the server has been up (resets on restart). + cpu_idle: + type: number + description: CPU idle time. + ServerStatsCpuUsage: + title: ServerStatsCpuUsage + type: object + properties: + user: + type: integer + nice: + type: integer + system: + type: integer + idle: + type: integer + iowait: + type: integer + irq: + type: integer + soft_irq: + type: integer + steal: + type: integer + guest: + type: integer + guest_nice: + type: integer + ServerStatsCpu: + title: ServerStatsCpu + type: object + description: Statistics about the CPU resources on a server. + properties: + physical_cpus: + type: integer + description: The number of physical CPU's for a given server. + cores: + type: integer + description: The number vCPU's for a given server. + threads: + type: integer + description: The number of CPU threads for a given server. + processors: + description: An array of processor information objects. + type: array + items: + type: object + description: Processor information. + properties: + model: + type: string + description: The model of the processor. + speed: + type: number + format: float + description: The speed of the processor. + usage: + $ref: '#/components/schemas/ServerStatsCpuUsage' + virtualization: + description: A true value indicates the server supports virtualization. + type: boolean + ServerStatsLoad: + title: ServerStatsLoad + type: object + description: Statistics about the current load on the server. + required: + - avg1m + - avg5m + - avg15m + properties: + avg1m: + type: number + format: float + description: The 1 minute load average. + avg5m: + type: number + format: float + description: The 5 minute load average. + avg15m: + type: number + format: float + description: the 15 minute load average. + ServerStatsRam: + title: ServerStatsRam + type: object + description: Statistics about the RAM on a given server. + required: + - available + - free + - total + properties: + available: + type: integer + description: The available RAM on the server. + free: + type: integer + description: The free RAM on the server. + total: + type: integer + description: The total RAM on the server. + ServerStatsStorage: + title: ServerStatsStorage + type: object + description: Statistics about storage for a given server. + required: + - volume_groups + - mounts + properties: + volume_groups: + description: An array of volume group objects. + type: object + additionalProperties: + type: object + description: Volume group + required: + - name + - size + - volumes + properties: + name: + type: string + description: A name for the volume group. + size: + type: integer + description: A number representing the aggregate group volume size in megabytes. + volumes: + description: The actual volumes. + type: object + additionalProperties: + type: object + required: + - name + - size + - data_percent + - meta_percent + - pool + properties: + name: + type: string + description: The name of the volume. + size: + type: integer + description: The size in megabytes of the volume. + data_percent: + type: integer + description: The percent of the volumes size being used by data. + meta_percent: + type: integer + description: The percent of the volumes size being used by meta data. + pool: + type: string + description: The name of the volume pool this volume is associated with. + mounts: + type: object + description: Records that show information about mounted filesystems where the key is the path to the mount. + additionalProperties: + title: MountedFS + type: object + description: Mounted filesystem information. + required: + - type + - total + - free + - used + properties: + device: + type: string + description: The device assocaited with the mount. + type: + type: string + description: The type of filesystem in use by the mount. + mountpoint: + type: string + description: The path the mount is associated with. + total: + type: integer + description: The total amount of storage in KB available at this mount. + free: + type: integer + description: The amount of uninitialized storage in KB. + used: + type: integer + description: The amount of storage being used in KB. + ServerStatsOS: + title: ServerStatsOS + type: object + description: Statistics about the operating system installed on the server (CycleOS). + properties: + release: + type: string + description: The currently installed release version of the OS. + kernel: + type: string + description: The currently installed kernel version. + hostname: + type: string + description: The hostname as set by the given server's OS. + ServerStatsVendor: + title: ServerStatsVendor + type: object + description: Details about the vendors for the server. + properties: + system_vendor: + type: string + description: The system vendor of the server. + board_vendor: + type: string + description: The board vendor of the server. + board_name: + type: string + description: The board name of the server. + board_serial: + type: string + description: The board serial number of the server. + bios_vendor: + type: string + description: The bios vendor of the server. + ServerStatsVersions: + title: ServerStatsVersions + type: object + description: Information about the versions of Cycle services on a given server. + required: + - services + properties: + services: + description: A list of records about Cycle services. + type: object + additionalProperties: + type: string + NodeMetaStats: + title: NodeMetaStats + type: object + description: Statistics that pertain to a specific node. + required: + - network + - uptime + - cpu + - load + - ram + - storage + - os + - vendor + - versions + properties: + network: + $ref: '#/components/schemas/ServerStatsNetwork' + uptime: + $ref: '#/components/schemas/ServerStatsUptime' + cpu: + $ref: '#/components/schemas/ServerStatsCpu' + load: + $ref: '#/components/schemas/ServerStatsLoad' + ram: + $ref: '#/components/schemas/ServerStatsRam' + storage: + $ref: '#/components/schemas/ServerStatsStorage' + os: + $ref: '#/components/schemas/ServerStatsOS' + vendor: + $ref: '#/components/schemas/ServerStatsVendor' + versions: + $ref: '#/components/schemas/ServerStatsVersions' + ServerMeta: + title: ServerMeta + type: object + description: A list of meta fields that can be applied to a server. + properties: + node: + type: object + description: Infrormation about the status of the server. + required: + - last_checkin + - drivers + - state + - stats + - healthy + - online + properties: + last_checkin: + description: The last time this server checked in with the platform. + $ref: '#/components/schemas/DateTime' + drivers: + description: An array a drivers associated with the given server. + type: array + items: + type: string + state: + $ref: '#/components/schemas/NodeState' + stats: + $ref: '#/components/schemas/NodeMetaStats' + healthy: + type: boolean + description: A boolean where true means the platform is reporting the server as healthy. + online: + type: boolean + description: A boolean where true means the server is online and reachable by the platform. + instances_count: + $ref: '#/components/schemas/StateCountSummary' + allocations: + type: object + required: + - cpu_shares + - ram + properties: + cpu_shares: + type: object + required: + - total + - allocatable + - allocated + properties: + total: + type: integer + allocatable: + type: integer + allocated: + type: integer + ram: + type: object + required: + - total_mb + - allocatable_mb + - allocated_mb + properties: + total_mb: + type: integer + allocatable_mb: + type: integer + allocated_mb: + type: integer + Server: + title: Server + type: object + description: The server resource, referring to servers that have been deployed to a Cycle hub. + required: + - id + - hub_id + - location_id + - model_id + - node_id + - shared_file_systems + - hostname + - creator + - provider + - cluster + - features + - constraints + - ephemeral + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + hub_id: + $ref: '#/components/schemas/HubID' + location_id: + type: string + description: An identifier for the location this server is deployed to. + model_id: + type: string + description: An identifier for the model of server that is deployed. + node_id: + type: string + description: An identifier for the node. + shared_file_systems: + $ref: '#/components/schemas/ServerSharedFileSystems' + hostname: + type: string + description: The server hostname. + nickname: + description: A custom name given to the server for identification purposes. Does not affect server hostname. + type: + - string + - 'null' + creator: + $ref: '#/components/schemas/CreatorScope' + provider: + $ref: '#/components/schemas/ServerProvider' + cluster: + type: string + description: The cluster the given server is deployed to. + features: + $ref: '#/components/schemas/ServerFeatures' + constraints: + $ref: '#/components/schemas/ServerConstraints' + autoscale: + oneOf: + - type: object + required: + - group_id + properties: + group_id: + $ref: '#/components/schemas/ID' + - type: 'null' + ephemeral: + type: boolean + description: Set to true when a server is created as part of an auto-scale event. + evacuate: + description: Details about a server's evacuation status. When an evacuation is in progress, no new container instances will be permitted on the server. + oneOf: + - type: object + required: + - started + properties: + started: + description: The time when this server began evacuating instances. + $ref: '#/components/schemas/DateTime' + - type: 'null' + state: + $ref: '#/components/schemas/ServerState' + events: + title: ServerEvents + type: object + description: A collection of timestamps for each event in the server's lifetime. + required: + - created + - updated + - deleted + - latest_instance + - provisioning + properties: + created: + description: The timestamp of when the server was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the server was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the server was deleted. + $ref: '#/components/schemas/DateTime' + latest_instance: + description: The timestamp of when the latest instance was deployed to this server. + $ref: '#/components/schemas/DateTime' + provisioning: + type: object + description: Information about the provisioning of the server. + required: + - started + - failed + - completed + properties: + started: + description: A timestamp of when the server started provisioning. + $ref: '#/components/schemas/DateTime' + failed: + description: A timestamp of when the server failed provisioning. + $ref: '#/components/schemas/DateTime' + completed: + description: A timestamp of when the server completed provisioning. + $ref: '#/components/schemas/DateTime' + meta: + $ref: '#/components/schemas/ServerMeta' + VirtualMachineMeta: + title: VirtualMachineMeta + type: object + description: Fields that can be included on a per-virtual machine basis, specific to that virtual machine. + properties: + domains: + anyOf: + - type: array + items: + type: object + description: Any associated LINKED records for this virtual machine, and their fully-qualified domain name (fqdn). + properties: + fqdn: + type: string + description: The fully qualified domain name. + record: + anyOf: + - $ref: '#/components/schemas/DnsRecord' + - type: 'null' + required: + - fqdn + - type: 'null' + ips: + description: An array of public IP addresses associated with this virtual machine. + anyOf: + - type: array + items: + $ref: '#/components/schemas/Ip' + - type: 'null' + server: + description: The server the virtual machine is deployed to. + anyOf: + - $ref: '#/components/schemas/Server' + - type: 'null' + hypervisor_ips: + description: An array of private IP addresses associated with the hypervisor for this virtual machine.. + anyOf: + - type: object + properties: + ipv4: + type: string + ipv6: + type: string + - type: 'null' + VirtualMachine: + title: VirtualMachine + type: object + description: | + Describes a virtual machine running on the Cycle Platform. + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: A user-defined name for the virtual machine. + identifier: + $ref: '#/components/schemas/Identifier' + creator: + $ref: '#/components/schemas/CreatorScope' + environment: + type: object + description: | + Basic information about the environment this virtual machine is in. + properties: + id: + $ref: '#/components/schemas/ID' + cluster: + $ref: '#/components/schemas/Identifier' + description: The cluster this environment is associated with. + required: + - id + - cluster + hub_id: + $ref: '#/components/schemas/HubID' + config: + $ref: '#/components/schemas/VirtualMachineConfig' + image: + $ref: '#/components/schemas/VirtualMachineImage' + container_id: + $ref: '#/components/schemas/ID' + volumes: + anyOf: + - type: array + items: + $ref: '#/components/schemas/VirtualMachineVolume' + - type: 'null' + annotations: + description: Metadata annotations for the virtual machine. + oneOf: + - type: object + additionalProperties: {} + - type: 'null' + root_password: + type: object + description: The generated root password for the virtual machine. Only visible by the owner, or if it was created in the last ten minutes. + properties: + changed: + $ref: '#/components/schemas/DateTime' + current: + type: + - string + - 'null' + description: The root password. + required: + - changed + - current + ssh_keys: + description: An array of IDs corresponding to SSH keys that have been assigned to this virtual machine. + anyOf: + - type: array + items: + $ref: '#/components/schemas/ID' + - type: 'null' + state: + $ref: '#/components/schemas/VirtualMachineState' + events: + title: VirtualMachineEvents + type: object + description: A collection of timestamps for each event in the virtual machine's lifetime. + required: + - created + - updated + - deleted + - started + properties: + created: + description: The timestamp of when the virtual machine was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the virtual machine was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the virtual machine was deleted. + $ref: '#/components/schemas/DateTime' + started: + description: The timestamp of when the virtual machine was started. + $ref: '#/components/schemas/DateTime' + deprecate: + type: boolean + description: A boolean flag indicating if this virtual machine is deprecated. + lock: + type: boolean + description: Prevents this virtual machine from being deleted when true. + meta: + anyOf: + - $ref: '#/components/schemas/VirtualMachineMeta' + - type: 'null' + required: + - id + - name + - identifier + - creator + - environment + - hub_id + - config + - image + - state + - events + - deprecate + - lock + LoadBalancerTelemetryRouterMetrics: + title: LoadBalancerTelemetryRouterMetrics + type: object + required: + - destinations + properties: + destinations: + type: object + additionalProperties: + type: object + required: + - connections + - requests + - instance_id + - container_id + properties: + connections: + type: + - object + - 'null' + required: + - success + - unavailable + properties: + success: + type: integer + unavailable: + type: integer + errors: + type: object + additionalProperties: + type: integer + bytes_transmitted: + type: integer + bytes_received: + type: integer + requests: + type: + - object + - 'null' + required: + - total + properties: + total: + type: integer + responses: + type: object + additionalProperties: + type: integer + errors: + type: object + additionalProperties: + type: integer + latency_ms: + type: array + items: + type: integer + instance_id: + type: string + container_id: + type: string + LoadBalancerTelemetryUrlRequestHandler: + title: LoadBalancerTelemetryUrlRequestHandler + type: object + required: + - hits + - timing_ms + properties: + hits: + description: The number of hits to a specific URL handler. + type: integer + timing_ms: + description: The cumulative ms of response time across all hits. + type: integer + LoadBalancerTelemetryUrlMetrics: + title: LoadBalancerTelemetryUrlMetrics + type: object + required: + - destinations + properties: + destinations: + type: object + additionalProperties: + type: object + required: + - requests + properties: + requests: + type: + - object + - 'null' + required: + - host + - method + - path + - total + - last_hit + - handlers + properties: + host: + type: string + description: The host name of the URL request. + examples: + - abc.cycle.io + method: + type: string + description: The HTTP method of the URL request. + examples: + - GET + path: + type: string + description: The path portion of the inbound URL request. + examples: + - /pathname + total: + type: integer + description: The number of requests to a this URL. + examples: + - 5 + - 10 + last_hit: + description: The date of the most recent hit to the URL. + $ref: '#/components/schemas/DateTime' + handlers: + type: object + description: An object describing the relative breakdown of proxy, cache, forward, and redirect URL responses. + required: + - proxy + - cache + - forward + - redirect + properties: + proxy: + description: Object containing hit count and timing data for proxy responses. + $ref: '#/components/schemas/LoadBalancerTelemetryUrlRequestHandler' + cache: + description: Object containing hit count and timing data for cache responses. + $ref: '#/components/schemas/LoadBalancerTelemetryUrlRequestHandler' + forward: + description: Object containing hit count and timing data for forward responses. + $ref: '#/components/schemas/LoadBalancerTelemetryUrlRequestHandler' + redirect: + description: Object containing hit count and timing data for redirect responses. + $ref: '#/components/schemas/LoadBalancerTelemetryUrlRequestHandler' + responses: + type: object + examples: + - http:404: 10 + description: An object where the key is the response type and the value is the number of hits with that response. + additionalProperties: + type: integer + errors: + type: object + examples: + - i/o timeout: 1 + description: An object where the key is the error type and the value is the number of hits with that error. + additionalProperties: + type: integer + LoadBalancerTelemetryControllerMetrics: + title: LoadBalancerTelemetryControllerMetrics + type: object + required: + - disconnects + - connections + - requests + - bytes_transmitted + - bytes_received + properties: + disconnects: + title: LoadBalancerTelemetryControllerDisconnectsMetrics + type: object + required: + - no_error + - request_invalid + - timeout_idle + - router_none + - router_nomatch + - destination_unavailable + - unknown_error + properties: + no_error: + type: integer + request_invalid: + type: integer + timeout_idle: + type: integer + router_none: + type: integer + router_nomatch: + type: integer + destination_unavailable: + type: integer + unknown_error: + type: integer + connections: + type: integer + requests: + type: integer + bytes_transmitted: + type: integer + bytes_received: + type: integer + LoadBalancerTelemetrySnapshot: + title: LoadBalancerTelemetrySnapshot + type: object + required: + - time + - started + - dataset_id + - current + - cumulative + properties: + time: + $ref: '#/components/schemas/DateTime' + started: + $ref: '#/components/schemas/DateTime' + version: + type: string + dataset_id: + type: integer + current: + type: object + required: + - metrics + properties: + router: + anyOf: + - $ref: '#/components/schemas/LoadBalancerTelemetryRouterMetrics' + - type: 'null' + urls: + anyOf: + - $ref: '#/components/schemas/LoadBalancerTelemetryUrlMetrics' + - type: 'null' + metrics: + $ref: '#/components/schemas/LoadBalancerTelemetryControllerMetrics' + cumulative: + type: object + required: + - metrics + properties: + router: + anyOf: + - $ref: '#/components/schemas/LoadBalancerTelemetryRouterMetrics' + - type: 'null' + urls: + anyOf: + - $ref: '#/components/schemas/LoadBalancerTelemetryUrlMetrics' + - type: 'null' + metrics: + $ref: '#/components/schemas/LoadBalancerTelemetryControllerMetrics' + HubEvents: + title: HubEvents + type: object + description: A collection of timestamps for each event in the hub's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the hub was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the hub was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the hub was deleted. + $ref: '#/components/schemas/DateTime' + converted: + description: The timestamp of when the hub had the first converted. + $ref: '#/components/schemas/DateTime' + first_order: + description: The timestamp of when the hub had the first provider added. + $ref: '#/components/schemas/DateTime' + first_provider: + description: The timestamp of when the hub had the first provider added. + $ref: '#/components/schemas/DateTime' + first_server: + description: The timestamp of when the hub had the first_server deployed. + $ref: '#/components/schemas/DateTime' + first_environment: + description: The timestamp of when the hub had the first environment deployed. + $ref: '#/components/schemas/DateTime' + first_image: + description: The timestamp of when the hub had the first image deployed. + $ref: '#/components/schemas/DateTime' + first_container: + description: The timestamp of when the hub had the first container deployed. + $ref: '#/components/schemas/DateTime' + HubState: + title: HubState + allOf: + - required: + - current + properties: + current: + description: The current state of the hub. + type: string + enum: + - new + - configuring + - live + - inactive + - deleting + - deleted + - $ref: '#/components/schemas/State' + MembershipState: + title: MembershipState + allOf: + - required: + - current + properties: + current: + description: The current state of the membership. + type: string + enum: + - pending + - accepted + - declined + - revoked + - deleted + - $ref: '#/components/schemas/State' + Invitation: + title: HubMembershipInvitation + type: object + description: Information about a hub membership invitation. + required: + - sender + - recipient + - events + properties: + sender: + type: object + description: Information about the origin account of the invitation. + required: + - id + - type + properties: + id: + $ref: '#/components/schemas/ID' + type: + type: string + description: The account type. + recipient: + type: string + description: The email address for the invitations recipient. + events: + title: InvitationEvents + type: object + description: A collection of timestamps for each event in the invitation's lifetime. + required: + - created + - updated + - deleted + - accepted + - declined + - revoked + properties: + created: + description: The timestamp of when the invitation was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the invitation was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the invitation was deleted. + $ref: '#/components/schemas/DateTime' + accepted: + description: The timestamp of when the invitation was accepted. + $ref: '#/components/schemas/DateTime' + declined: + description: The timestamp of when the invitation was declined. + $ref: '#/components/schemas/DateTime' + revoked: + description: The timestamp of when the invitation was revoked. + $ref: '#/components/schemas/DateTime' + HubMembership: + title: HubMembership + type: object + description: A membership resource that is scoped to an individual hub. + required: + - id + - hub_id + - role_id + - events + - state + - invitation + - permissions + - prefereneces + properties: + id: + $ref: '#/components/schemas/ID' + account_id: + type: string + description: An ID for the account associated with the given membership. + hub_id: + $ref: '#/components/schemas/HubID' + events: + title: MembershipEvents + type: object + description: A collection of timestamps for each event in the membership's lifetime. + required: + - joined + properties: + created: + description: The timestamp of when the membership was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the membership was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the membership was deleted. + $ref: '#/components/schemas/DateTime' + joined: + description: The timestamp of when the membership was accepted. + $ref: '#/components/schemas/DateTime' + role_id: + definition: The ID of the Role assigned to this Hub Membership. + $ref: '#/components/schemas/ID' + preferences: + type: object + title: HubMembershipPreferences + description: Preference information set by the user for the membership. + required: + - portal + - email + properties: + portal: + type: object + required: + - notifications + properties: + notifications: + type: object + required: + - jobs + properties: + jobs: + type: object + required: + - apikey_alerts + properties: + apikey_alerts: + type: boolean + email: + type: object + required: + - notifications + properties: + notificaitons: + type: object + required: + - server + properties: + server: + type: object + required: + - new + - offline + properties: + new: + type: + - boolean + - 'null' + offline: + type: + - boolean + - 'null' + state: + $ref: '#/components/schemas/MembershipState' + invitation: + $ref: '#/components/schemas/Invitation' + cycle: + type: object + description: If this member is a Cycle employee, their employee ID will be listed here. Cycle employee accounts do not consume a "membership" for a given hub. + required: + - employee_id + properties: + employee_id: + type: string + description: The ID of the employee this membership is associated with. + HubMeta: + title: HubsMeta + type: object + description: A list of meta fields that can be applied to a hub. + properties: + membership: + $ref: '#/components/schemas/HubMembership' + PublicHub: + title: PublicHub + description: A hub with sensitive information stripped out. + type: object + required: + - id + - name + - events + - creator + - state + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: A name for the hub. + events: + $ref: '#/components/schemas/HubEvents' + creator: + $ref: '#/components/schemas/CreatorScope' + state: + $ref: '#/components/schemas/HubState' + meta: + $ref: '#/components/schemas/HubMeta' + IntegrationAuth: + title: IntegrationAuth + type: object + properties: + region: + type: + - string + - 'null' + description: The region associated with the Integration. + namespace: + type: + - string + - 'null' + description: The namespace associated with the Integration. + api_key: + type: + - string + - 'null' + description: API key for accessing the Integration. + key_id: + type: + - string + - 'null' + description: Key ID for accessing the Integration. + secret: + type: + - string + - 'null' + description: Secret for accessing the Integration. + subscription_id: + type: + - string + - 'null' + description: Subscription ID for the Integration. + client_id: + type: + - string + - 'null' + description: Client ID for the Integration. + base64_config: + type: + - string + - 'null' + description: Base64 encoded configuration for the Integration. + IntegrationState: + title: IntegrationState + allOf: + - required: + - current + properties: + current: + description: The current state of the integration. + type: string + enum: + - new + - verifying + - live + - deleting + - deleted + - $ref: '#/components/schemas/State' + IntegrationAdvancedOptionBoolean: + title: IntegrationAdvancedOptionBoolean + type: object + required: + - title + - key + - type + properties: + title: + type: string + key: + type: string + type: + type: string + enum: + - bool + default: + type: + - boolean + - 'null' + IntegrationAdvancedOptionInt: + title: IntegrationAdvancedOptionInt + type: object + required: + - title + - key + - type + properties: + title: + type: string + key: + type: string + type: + type: string + enum: + - int + default: + type: + - integer + - 'null' + IntegrationAdvancedOptionString: + title: IntegrationAdvancedOptionString + type: object + required: + - title + - key + - type + properties: + title: + type: string + key: + type: string + type: + type: string + enum: + - string + default: + type: + - string + - 'null' + IntegrationDefinitionField: + title: IntegrationDefinitionField + type: object + required: + - name + - required + properties: + regex: + type: + - string + - 'null' + required: + type: boolean + name: + type: string + description: + type: string + type: + type: string + enum: + - select + - string + - int + - blob + options: + oneOf: + - type: array + items: + type: string + - type: 'null' + IntegrationDefinition: + title: IntegrationDefinition + description: Describes an integration for a Cycle hub that can be enabled by the hub owner. + type: object + required: + - vendor + - name + - supports_verification + - supports_multiple + - required_fields + - url + - public + - usable + - editable + properties: + vendor: + type: string + name: + type: string + supports_verification: + type: boolean + supports_multiple: + type: boolean + features: + oneOf: + - type: array + description: A list of additional features supported by this integration. + items: + type: string + - type: 'null' + extends: + oneOf: + - type: array + description: A list of functionality that this integration extends. i.e. ["backups"] + items: + type: string + - type: 'null' + extended_configuration: + oneOf: + - type: object + description: Additional configuration options that are available when using this integration. These describe additional functionality that Cycle may utilize. + properties: + options: + oneOf: + - type: array + items: + type: object + discriminator: + propertyName: type + mapping: + bool: '#/components/schemas/IntegrationAdvancedOptionBoolean' + int: '#/components/schemas/IntegrationAdvancedOptionInt' + string: '#/components/schemas/IntegrationAdvancedOptionString' + oneOf: + - $ref: '#/components/schemas/IntegrationAdvancedOptionBoolean' + - $ref: '#/components/schemas/IntegrationAdvancedOptionInt' + - $ref: '#/components/schemas/IntegrationAdvancedOptionString' + - type: 'null' + - type: 'null' + fields: + type: object + properties: + extra: + oneOf: + - type: object + additionalProperties: + $ref: '#/components/schemas/IntegrationDefinitionField' + - type: 'null' + auth: + oneOf: + - type: object + additionalProperties: + $ref: '#/components/schemas/IntegrationDefinitionField' + - type: 'null' + url: + type: string + format: uri + public: + type: boolean + usable: + type: boolean + description: Whether or not this integration can be used at this time. + deprecated: + type: boolean + description: If true, this integration is no longer being supported and may be removed in the future. New instances of this integration will not be able to be created. + editable: + type: boolean + description: If true, the integration can be edited. Otherwise, to make a change it will need to be deleted and recreated. + IntegrationMeta: + title: IntegrationMeta + type: object + description: Additional fields that can be requested for an Integration on fetch. + properties: + definition: + $ref: '#/components/schemas/IntegrationDefinition' + description: The full Integration definition associated with this Integration. + Integration: + title: Integration + type: object + required: + - id + - identifier + - name + - vendor + - creator + - hub_id + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: Name of the integration. + vendor: + type: string + description: Which vendor this integration is associated with. + identifier: + $ref: '#/components/schemas/Identifier' + auth: + description: Authentication information for the integration, can be null. + anyOf: + - $ref: '#/components/schemas/IntegrationAuth' + - type: 'null' + extra: + description: Updated key-value pairs associated with the integration. + oneOf: + - type: object + additionalProperties: + type: string + - type: 'null' + creator: + $ref: '#/components/schemas/CreatorScope' + hub_id: + $ref: '#/components/schemas/ID' + description: Identifier of the hub associated with the integration. + state: + $ref: '#/components/schemas/IntegrationState' + events: + title: IntegrationEvents + type: object + description: A collection of timestamps for each event in the integration's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the integration was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the integration was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the integration was deleted. + $ref: '#/components/schemas/DateTime' + meta: + anyOf: + - $ref: '#/components/schemas/IntegrationMeta' + - type: 'null' + ExternalVolumeAbout: + title: ExternalVolumeAbout + type: object + description: Additional details about the external volume. + required: + - description + properties: + description: + description: Custom details about this external volume. + type: string + SourceSanIscsi: + title: SourceSanIscsi + type: object + description: | + A SAN iSCSI volume source. Defines one or more iSCSI targets and the LUN number to attach. + required: + - type + - details + properties: + type: + type: string + enum: + - san-iscsi + details: + type: object + required: + - integration_ids + - lun + properties: + integration_ids: + description: | + One or more iSCSI integration IDs to use for authentication. + type: array + items: + $ref: '#/components/schemas/ID' + lun: + type: integer + format: int32 + description: | + Logical Unit Number exposed by the target(s) to attach. + SourceCephRbdImageRef: + title: SourceCephRbdImageRef + type: object + description: Reference to the specific RBD image to attach. + required: + - pool + - name + properties: + pool: + type: string + description: Name of the Ceph pool containing the RBD image. + namespace: + type: string + description: Optional RBD namespace within the pool. + name: + type: string + description: Name of the RBD image. + snapshot: + type: string + description: Optional snapshot name if attaching a snapshot view of the image. + SourceCephRbd: + title: SourceCephRbd + type: object + description: | + A Ceph RBD volume source. Defines monitor endpoints, optional cluster FSID, client identity (CephX), and the specific image to attach. + required: + - type + - details + properties: + type: + type: string + enum: + - ceph-rbd + details: + type: object + required: + - integration_id + - image + properties: + integration_id: + description: | + The ID of a Ceph cluster integration for authentication. + $ref: '#/components/schemas/ID' + image: + $ref: '#/components/schemas/SourceCephRbdImageRef' + SourceAwsEbsAuth: + title: SourceAwsEbsAuth + type: object + description: | + AWS credentials for accessing EBS. Either an instance role may be used or explicit Access Key credentials may be provided. + properties: + use_instance_role: + type: boolean + description: | + When true, use the instance's IAM role for authentication. + access_key_id: + type: string + description: | + AWS Access Key ID to use for authentication (optional if using instance role). + secret_access_key: + type: string + format: password + description: | + AWS Secret Access Key to use for authentication (optional if using instance role). + SourceAwsEbsRef: + title: SourceAwsEbsRef + type: object + description: Reference to the specific EBS volume to attach. + required: + - volume_id + properties: + volume_id: + type: string + description: | + The EBS volume ID (for example, "vol-0abcd1234ef567890"). + az: + type: string + description: | + Optional AWS Availability Zone where the volume resides (for example, "us-east-1a"). + SourceAwsEbs: + title: SourceAwsEbs + type: object + description: | + An AWS EBS volume source. Defines how to authenticate to AWS and which EBS volume to attach. + required: + - type + - details + properties: + type: + type: string + enum: + - aws-ebs + details: + type: object + required: + - auth + - volume + properties: + auth: + $ref: '#/components/schemas/SourceAwsEbsAuth' + volume: + $ref: '#/components/schemas/SourceAwsEbsRef' + ExternalVolumeSource: + title: ExternalVolumeSource + description: | + The source information for this volume. + oneOf: + - $ref: '#/components/schemas/SourceSanIscsi' + - $ref: '#/components/schemas/SourceCephRbd' + - $ref: '#/components/schemas/SourceAwsEbs' + discriminator: + propertyName: type + mapping: + san-iscsi: '#/components/schemas/SourceSanIscsi' + ceph-rbd: '#/components/schemas/SourceCephRbd' + aws-ebs: '#/components/schemas/SourceAwsEbs' + ExternalVolumeAttachmentBlock: + title: ExternalVolumeAttachmentBlock + type: object + description: Configuration for a block volume attachment. + required: + - type + - mode + - details + properties: + type: + type: string + enum: + - block + mode: + type: string + description: The access mode for the attachment. + enum: + - single-instance-writer + - single-instance-read-only + - single-node-writer + - single-node-read-only + - multi-node-writer + - multi-node-read-only + details: + type: object + description: Details for a block attachment. Present when `type` is `block`. + properties: {} + additionalProperties: false + ExternalVolumeAttachmentFileSystem: + title: ExternalVolumeAttachmentFileSystem + type: object + description: Configuration for a filesystem volume attachment. + required: + - type + - mode + - details + properties: + type: + type: string + enum: + - filesystem + mode: + type: string + description: The access mode for the attachment. + enum: + - single-instance-writer + - single-instance-read-only + - single-node-writer + - single-node-read-only + - multi-node-writer + - multi-node-read-only + details: + type: object + description: Details for a filesystem attachment. Present when `type` is `filesystem`. + properties: {} + additionalProperties: false + ExternalVolumeAttachment: + title: ExternalVolumeAttachment + type: object + description: Attachment configuration for an external volume. + discriminator: + propertyName: type + mapping: + block: '#/components/schemas/ExternalVolumeAttachmentBlock' + filesystem: '#/components/schemas/ExternalVolumeAttachmentFileSystem' + oneOf: + - $ref: '#/components/schemas/ExternalVolumeAttachmentBlock' + - $ref: '#/components/schemas/ExternalVolumeAttachmentFileSystem' + ExternalVolumeOptions: + title: ExternalVolumeOptions + type: object + description: Configuration options controlling the behavior of the volume. + required: + - create + properties: + create: + description: | + If the volume doesn't exist, attempt to create it on container start if create struct defined. + oneOf: + - type: object + required: + - size + properties: + size: + description: Indicates the size of volume to create. + $ref: '#/components/schemas/DataSize' + - type: 'null' + ExternalVolumeState: + title: ExternalVolumeState + allOf: + - required: + - current + properties: + current: + description: The current lifecycle state of the volume. + type: string + enum: + - new + - ready + - configuring + - live + - deleting + - deleted + - $ref: '#/components/schemas/State' + ExternalVolumeEvents: + title: ExternalVolumeEvents + type: object + description: Timestamps for events that happen over the lifetime of the attached volume. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the attached volume was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the attached volume was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the attached volume was deleted. + $ref: '#/components/schemas/DateTime' + last_verified: + $ref: '#/components/schemas/DateTime' + description: | + Timestamp of the last successful verification event for this volume. + last_sync: + $ref: '#/components/schemas/DateTime' + description: | + Timestamp of the last successful synchronization event for this volume. + ContainerSummary-2: + title: ContainerSummary + type: object + description: Lightweight summary of a container for environment pages and lists. + required: + - id + - name + - state + - image + - environment + - volumes + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: A user defined name for the container. + state: + $ref: '#/components/schemas/ContainerState' + image: + $ref: '#/components/schemas/ImageSummary' + environment: + $ref: '#/components/schemas/ContainerEnvironmentSummary' + volumes: + type: array + items: + $ref: '#/components/schemas/VolumeSummary' + ExternalVolumeMeta: + title: ExternalVolumeMeta + type: object + description: A list of meta fields that can be applied to an attached volume. + properties: + containers: + type: array + items: + $ref: '#/components/schemas/ContainerSummary-2' + ExternalVolume: + title: ExternalVolume + type: object + description: | + A persistent storage volume within a cluster. Volumes may be attached to containers or VMs and can originate from different storage sources. + required: + - id + - hub_id + - name + - about + - cluster + - location_id + - server_ids + - source + - options + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + hub_id: + $ref: '#/components/schemas/HubID' + name: + type: string + description: The name of the external volume. + about: + $ref: '#/components/schemas/ExternalVolumeAbout' + cluster: + $ref: '#/components/schemas/Identifier' + identifier: + oneOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + location_id: + $ref: '#/components/schemas/ID' + server_ids: + type: array + items: + $ref: '#/components/schemas/ID' + source: + $ref: '#/components/schemas/ExternalVolumeSource' + attachment: + description: Information about the resource the external volume is currently attached to. + oneOf: + - $ref: '#/components/schemas/ExternalVolumeAttachment' + - type: 'null' + size: + description: | + Size of the external volume; may be null or omitted if the size has not yet been determined. + oneOf: + - $ref: '#/components/schemas/DataSize' + - type: 'null' + options: + $ref: '#/components/schemas/ExternalVolumeOptions' + state: + $ref: '#/components/schemas/ExternalVolumeState' + events: + $ref: '#/components/schemas/ExternalVolumeEvents' + meta: + $ref: '#/components/schemas/ExternalVolumeMeta' + Certificate: + title: Certificate + description: A DNS TLS certificate. + type: object + required: + - id + - domains + - private_key + - bundle + - hub_id + properties: + id: + $ref: '#/components/schemas/ID' + domains: + type: array + description: An array of domains associated with the certificate. + items: + type: string + private_key: + type: string + description: The certificates private key. + bundle: + type: string + description: A bundle of certificates that are used to verify authenticity. + hub_id: + $ref: '#/components/schemas/HubID' + Metric: + title: Metric + description: A data point submitted to the monitoring system. + type: object + required: + - metric + - type + properties: + metric: + type: string + description: The title of the metric this data point refers to. + type: + type: string + description: The type of metric + enum: + - gauge + - count + - counter + - rate + - histogram + - distribution + - set + labels: + type: object + description: Any associated labels for the data, which can be used in querying. + additionalProperties: + type: string + tags: + type: array + description: Additional tags for the data point. + items: + type: string + points: + type: array + items: + type: object + required: + - time + properties: + time: + $ref: '#/components/schemas/DateTime' + values: + type: array + items: + type: integer + Event: + title: Event + description: A custom event submitted to the monitoring system. + type: object + required: + - event + - type + - priority + properties: + metadata: + anyOf: + - type: object + properties: + component: + type: object + description: The associated component for this event. + properties: + id: + type: string + type: + type: string + - type: 'null' + event: + type: string + description: The event name. + type: + type: string + enum: + - info + - warning + - error + - success + - alert + - notice + - audit + priority: + type: string + enum: + - critical + - high + - medium + - normal + - low + text: + description: The text describing the event that has occurred. + type: + - string + - 'null' + extra: + type: object + additionalProperties: true + labels: + type: object + additionalProperties: + type: string + tags: + type: array + items: + type: string + NetworkState: + title: NetworkState + allOf: + - required: + - current + properties: + current: + description: The current state of the network. + type: string + enum: + - live + - deleting + - deleted + - $ref: '#/components/schemas/State' + NetworkL2DhcpDetails: + title: NetworkL2DhcpDetails + type: object + required: + - method + properties: + method: + type: string + enum: + - dhcp + details: + type: object + maxProperties: 0 + NetworkL2StaticDetails: + title: NetworkL2StaticDetails + type: object + required: + - method + - details + properties: + method: + type: string + enum: + - static + details: + type: object + properties: + ipv4: + oneOf: + - type: object + required: + - network + - usable + properties: + network: + description: The CIDR for the network. + type: string + usable: + description: The usable CIDR. + type: string + gateway: + description: The IP of the gateway + type: + - string + - 'null' + - type: 'null' + ipv6: + oneOf: + - type: object + required: + - network + - usable + properties: + network: + description: The CIDR for the network. + type: string + usable: + description: The usable CIDR. + type: string + gateway: + description: The IP of the gateway + type: + - string + - 'null' + - type: 'null' + NetworkL2: + title: NetworkL2 + type: object + description: Layer 2 network information for a Cycle SDN. + required: + - ips + - location_ids + properties: + domain: + anyOf: + - $ref: '#/components/schemas/L2Domain' + - type: 'null' + location_ids: + type: array + items: + $ref: '#/components/schemas/ID' + vid: + type: + - integer + - 'null' + host_interface: + type: + - string + - 'null' + routes: + description: An array of L2 routes that are added to this SDN + type: array + items: + type: object + required: + - network + properties: + network: + $ref: '#/components/schemas/Cidr' + gateway: + $ref: '#/components/schemas/IpAddress' + ips: + discriminator: + propertyName: method + mapping: + dhcp: '#/components/schemas/NetworkL2DhcpDetails' + static: '#/components/schemas/NetworkL2StaticDetails' + oneOf: + - $ref: '#/components/schemas/NetworkL2DhcpDetails' + - $ref: '#/components/schemas/NetworkL2StaticDetails' + NetworkPrivacySettings: + title: NetworkPrivacySettings + type: object + description: Private network information for a Cycle SDN. + required: + - vxlan_tag + - subnet + - mac_addr_suffix + - ipv6 + properties: + vxlan_tag: + type: integer + description: A tag used to ensure proper routing. + subnet: + type: string + description: The subnet of the private network. + mac_addr_suffix: + type: integer + description: A number used to ensure a MAC address exists for each network. + ipv6: + type: object + description: IPv6 infromation for the network. + required: + - ip + - cidr + properties: + ip: + type: string + description: The networks IPv6 base. + cidr: + type: string + description: The private network CIDR. + Network: + title: Network + type: object + description: SDN Network resource. + required: + - id + - name + - identifier + - cluster + - creator + - hub_id + - state + - events + properties: + id: + $ref: '#/components/schemas/ID' + name: + type: string + description: The name of the network. + identifier: + type: string + description: A network identifier used to construct http calls that specifically use this network over another. + cluster: + type: string + description: The infrastructure cluster the environments belonging to this network belong to. + creator: + $ref: '#/components/schemas/CreatorScope' + hub_id: + $ref: '#/components/schemas/HubID' + state: + $ref: '#/components/schemas/NetworkState' + l2: + anyOf: + - $ref: '#/components/schemas/NetworkL2' + - type: 'null' + private_network: + anyOf: + - $ref: '#/components/schemas/NetworkPrivacySettings' + - type: 'null' + environments: + description: An array of environments and timestamps. + type: + - array + - 'null' + items: + type: object + required: + - id + - added + properties: + id: + $ref: '#/components/schemas/ID' + added: + description: A timestamp of when the environment was added. + $ref: '#/components/schemas/DateTime' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + events: + title: NetworkEvents + type: object + description: A collection of timestamps for each event in the network's lifetime. + required: + - created + - updated + - deleted + properties: + created: + description: The timestamp of when the image was created. + $ref: '#/components/schemas/DateTime' + updated: + description: The timestamp of when the image was updated. + $ref: '#/components/schemas/DateTime' + deleted: + description: The timestamp of when the image was deleted. + $ref: '#/components/schemas/DateTime' + ObjectCacheSave: + title: ObjectCacheSave + description: An item saved in the internal API object cache. + type: object + required: + - scope + - expires + - key + - value + properties: + scope: + type: string + enum: + - global + - environment + - container + - instance + expires: + $ref: '#/components/schemas/Duration' + key: + type: string + value: + type: string + responses: + DefaultError: + description: General error response from the platform + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' diff --git a/dist/platform.yml b/dist/platform.yml new file mode 100644 index 00000000..3a5ac50e --- /dev/null +++ b/dist/platform.yml @@ -0,0 +1,36961 @@ +openapi: 3.1.0 +info: + license: + name: Apache-2.0 + url: http://www.apache.org/licenses/LICENSE-2.0 + x-logo: + url: https://static.cycle.io/icons/logo/logo-white.svg + description: | + The Cycle Platform API is a [REST-based](http://en.wikipedia.org/wiki/Representational_state_transfer), resource-oriented API + designed to be easy to use and understand. Using this API, you are able to fully interact with the Cycle Platform. + + All API responses return JSON, including errors. There is also support for cross-origin resource sharing, so this API can be used + in a client-side web application as well. + + ## Auth Basics + Every API request much have an accompanying API key in the Authorization header. For more information on generating an API key head over to the [Portal Docs](https://cycle.io/docs/portal/managing-an-api-key-and-settings#creating-an-api-key). + + Your API key should never be made publicly available, published to a public repository, or used on a client side + web app. If you would like to use the API from a web app, you should create a thin-client service that acts as a passthrough for + your API requests. + + ## 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. + + The root resource. If fetching a collection, this will be an array of resource objects. + + 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 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). + + ## Scope + In order to fetch resources that are part of a hub (containers, environments, etc.), you will need to pass an + X-Hub-ID header. When fetching collections of resources, this will limit the response to contain only resources from + the specified hub. Most requests require this header. + + ## Queries + When trying to gather more complete or specific data you can use query parameters to supplement the normal return (metas, + includes) and you can also add specificity to the format and the order (sort, filter). It's worth understanding that + sort & filter should only be used on collections. + + **Sort** - An array of sort values. To sort descending, put a `-`n front of the value, i.e. `-id`. + + **Include** - An array of include values. Included resources will show up under the root document's `include` field, with the key being the id + of the included resource. In the case of applying an include to a collection of resources, if two resources share the same + include, it will only appear once in the return. + + **Meta** - An array of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a + collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to + individual resources, and may appear in the root document. These will be clearly labeled. + + **Filter** - The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + version: 1.0.0 + title: Cycle Platform API + contact: + email: support@cycle.io +servers: + - description: Cycle Platform API + url: https://api.cycle.io +security: + - bearerAuth: [] + hubAuth: [] +tags: + - name: Accounts + description: Endpoints related to managing your account on Cycle. + - name: Memberships + description: Endpoints related to account hub memberships, such as sending invitations to hubs or listing the hubs your account is a member of. + - name: Two-Factor Auth + description: Endpoints related to setting up two-factor authorization on a Cycle account. + - name: Announcements + description: Endpoints for reading announcements posted by the Cycle team. + - name: Credits + description: Endpoints related to credits applied to a hub. + - name: Invoices + description: Endpoints related to hub invoices, including the ability to pay an invoice. + - name: Methods + description: Endpoints related to managing payment methods associated with a hubs. + - name: Orders + description: Endpoints related to orders placed on a hub. + - name: Plans + description: Endpoints for fetching the available billing plans for a hub. + - name: Services + description: Endpoints related to the active services used by a hub. + - name: Containers + description: Endpoints related to managing containers, such as starting/stopping/reconfiguring and telemetry. + - name: Instances + description: Endpoints related to managing a container's instances, including connecting to the console and credentials for SSH. + - name: Backups + description: Endpoints related to managing container backups. + - name: Zones + description: Endpoints related to DNS zones. + - name: Records + description: Endpoints related to managing DNS zone records. + - name: TLS + description: Endpoints related to TLS certificate generation. + - name: Environments + description: Endpoints related to managing an environment. + - name: Deployments + description: Endpoints related to environment deployments. + - name: Scoped Variables + description: Endpoints related to managing an environment's scoped variables. + - name: Services/Discovery + description: Endpoints related to managing an environment's gateway service. + - name: Services/Gateway + description: Endpoints related to managing an environment's discovery service. + - name: Services/Load Balancer + description: Endpoints related to managing an environment's load balancer service. + - name: Services/Scheduler + description: Endpoints related to managing an envrionment's scheduler service. + - name: Services/VPN + description: Endpoints related to managing an environment's VPN service. + - name: Hubs + description: Endpoints related to managing hubs on Cycle. + - name: API Keys + description: Endpoints related to managing a hub's API keys. + - name: Integrations + description: Endpoints related to managing a hub's integrations. + - name: Hub Members + x-displayName: Members + description: Endpoints related to managing members of the current hub. + - name: Hub Notifications + x-displayName: Notifications + description: Endpoints related to receiving hub notifications. + - name: Roles + description: Endpoints related to managing a hub's role based access controls. + - name: Images + description: Endpoints related to managing container images. + - name: Image Sources + description: Endpoints related to managing image sources. + - name: Infrastructure + description: Endpoints related to managing physical/virtual infrastructure on Cycle. + - name: Auto-Scale Groups + description: Endpoints for managing groups of infrastructure that can be used for auto-scaling. + - name: Clusters + description: Endpoints related to managing infrastructure clusters. + - name: Providers + description: Endpoints related to providers configured for a hub. + - name: Virtual Providers + description: Endpoints related to virtual provider configurations. + - name: Servers + description: Endpoints related to managing servers on Cycle. + - name: SANs + description: Endpoints for managing SANs. + - name: IPs + description: Endpoints for managing IP allocations. + - name: Jobs + description: Endpoints related to managing long-running tasks, known as jobs, on Cycle. + - name: Monitoring + description: Endpoints related to gathered metrics for building dashboards, charts, and graphs. + - name: Pipelines + description: Endpoints related to pipelines, used for integrating with CI/CD solutions and automating deployments or other tasks. + - name: Trigger Keys + description: Endpoints for managing the trigger keys used to kick off a pipeline run. + - name: Networks + description: Endpoints for managing software-defined networks, for linking multiple environments together. + - name: Search + description: Endpoints related to search functionality on a hub. + - name: Stacks + description: Endpoints for managing Cycle stacks. + - name: Stack Builds + description: Endpoints for managing builds of a Cycle stack, including deploying a stack build to an environment. + - name: Virtual Machines + description: Endpoints for managing virtual machines. + - name: Utility + description: Extra utility endpoints that aren't related to a specific resource. +paths: + /v1/account: + get: + operationId: getAccount + summary: Get Account + description: Gets the Account associated with the authenticated bearer token. + security: + - bearerAuth: [] + tags: + - Accounts + responses: + '200': + description: Returns the Account. + content: + application/json: + schema: + title: AccountResponse + type: object + properties: + data: + $ref: '#/components/schemas/Account' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateAccount + tags: + - Accounts + summary: Update Account + description: Updates the Account. + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: object + description: The new name on the Account. + properties: + first: + type: string + last: + type: string + allow_support_login: + type: boolean + description: If true, Cycle employees will have the ability, upon consent, to access the account for support purposes. This access will be logged. + responses: + '200': + description: Returns the updated Account. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Account' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteAccount + tags: + - Accounts + summary: Delete Account + description: Puts the Account into a `deleted` state. This will fail if the Account is the current `OWNER` of an active Hub. + responses: + '202': + description: Returns a job descriptor with information about the status of the Account deletion. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/logins: + get: + operationId: getAccountLogins + summary: Get Account Logins + description: Lists logins associated with a given account. + security: + - bearerAuth: [] + tags: + - Accounts + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of login records associated with this Account. + content: + application/json: + schema: + title: AccountLoginsResponse + type: object + required: + - data + properties: + data: + type: array + items: + oneOf: + - $ref: '#/components/schemas/AccountEmployeeLogin' + - $ref: '#/components/schemas/AccountPasswordLogin' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/password: + patch: + operationId: changePassword + summary: Change Password + description: Change the password on the Account. Requires the current password of the Account to be submitted. + security: + - bearerAuth: [] + tags: + - Accounts + requestBody: + content: + application/json: + schema: + type: object + required: + - current + - new + properties: + current: + type: string + description: Current Password + new: + type: string + description: New Password + minLength: 8 + responses: + '200': + description: Returns an Account. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Account' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/reset-password: + post: + operationId: resetPassword + summary: Reset Password + description: Initiate a password reset for the Account. A confirmation email will be sent to the email associated with the Account, and the token in the email must be passed in a second call to this endpoint. + tags: + - Accounts + requestBody: + content: + application/json: + schema: + oneOf: + - type: object + required: + - email + properties: + email: + type: object + required: + - address + properties: + address: + type: string + - type: object + required: + - token + - password + properties: + token: + type: string + password: + type: string + responses: + '200': + description: Returns a simple object containing a success boolean. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - success + properties: + success: + type: boolean + default: + $ref: '#/components/responses/DefaultError' + /v1/account/invites: + get: + operationId: getAccountInvites + summary: List Account Invites + description: Lists the pending Hub Memberships (also known as Invites) associated with the Account. + security: + - bearerAuth: [] + tags: + - Memberships + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - capabilities + - $ref: '#/components/parameters/MembershipIncludeParam' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of pending Hub Memberships. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/AccountMembershipIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/invites/{inviteId}: + patch: + operationId: updateAccountInvite + summary: Accept or Reject an Invite + description: Accept/reject a pending Invite to join a Hub. + security: + - bearerAuth: [] + tags: + - Memberships + parameters: + - name: inviteId + description: The ID of the given Invite. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/MembershipIncludeParam' + requestBody: + content: + application/json: + schema: + type: object + properties: + accept: + type: boolean + description: If true, the Invite will be accepted and the associated Account will join the Hub. + decline: + type: boolean + description: If true, the Invite will be declined and the associated Account will NOT join the Hub. + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/AccountMembershipIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/memberships: + get: + operationId: getAccountMemberships + summary: Get Account Memberships + description: Lists the Hub Memberships for a given account. + security: + - bearerAuth: [] + tags: + - Memberships + parameters: + - $ref: '#/components/parameters/MembershipIncludeParam' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Hub Memberships associated with the Account. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubMembershipIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/2fa/setup: + get: + operationId: getTwoFactorAuthSetup + summary: Get Two-Factor Auth Setup + description: Gets the barcode and secret required for setting up two-factor authentication for the Account. + tags: + - Two-Factor Auth + parameters: [] + responses: + '200': + description: Returns necessary information for configuring two-factor auth for the Account. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/TwoFactorAuthSetup' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: enableTwoFactorAuth + summary: Enable Two-Factor Auth + description: Enables two-factor auth for the Account. Retrieve the token from an authenticator app using the secret from `getTwoFactorAuthSetup`. + tags: + - Accounts + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - token + properties: + token: + type: string + description: The token used to authenticate the two-factor setup. + responses: + '200': + description: Returns the recovery codes needed in case two-factor auth is no longer possible. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/TwoFactorAuthRecovery' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/2fa/disable: + post: + operationId: disableTwoFactorAuth + summary: Disable Two-Factor Auth + description: Disables two-factor auth for the account. + tags: + - Two-Factor Auth + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - token + properties: + token: + type: string + description: A valid existing two-factor auth token, for verification. + responses: + '200': + description: Returns the Account. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Account' + default: + $ref: '#/components/responses/DefaultError' + /v1/account/2fa/recover: + post: + operationId: recoverTwoFactorAuth + summary: Recover Two-Factor Auth + description: Returns a new two-factor auth setup to reset the Account's two-factor auth. + tags: + - Two-Factor Auth + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - email + - password + - recovery_codes + properties: + email: + type: string + description: The user's email + password: + type: string + recovery_codes: + type: array + items: + type: string + token: + type: string + responses: + '200': + description: Returns details for setting up two-factor auth. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/TwoFactorAuthSetup' + default: + $ref: '#/components/responses/DefaultError' + /v1/announcements: + get: + operationId: getAnnouncements + summary: Get Announcements + description: Lists any important updates posted by the Cycle team. + security: + - bearerAuth: [] + tags: + - Announcements + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + resolved: + description: Get only Announcements that have been resolved, or only those that have not. + type: string + enum: + - 'true' + - 'false' + range: + description: The start date from when to fetch the Announcements + type: string + enum: + - hour + - day + - week + - month + - year + responses: + '200': + description: List of announcements. + content: + application/json: + schema: + title: AnnouncementsListResponse + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Announcement' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/status: + get: + operationId: getBillingStatus + summary: Get Billing Status + description: | + Retrieve meta details about the billing status of this Cycle core. It is unlikely that someone would need this endpoint outside + of Cycle's internal teams. + tags: + - Billing + parameters: [] + responses: + '200': + description: Returns details about the billing status of this Cycle core. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + properties: + enabled: + type: boolean + description: Whether billing is enabled for this core. Generally, this will only be false for dedicated cores. + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/credits: + get: + operationId: getCredits + summary: List Billing Credits + description: | + Lists the Billing Credits associated with the current Hub. + + Requires the `billing-credits-view` capability. + tags: + - Credits + parameters: + - $ref: '#/components/parameters/SortParam' + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the credit's current state. + search: + type: string + description: Use a text-based search to filter the credits. + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a collection of credit resources. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Credit' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/credits/{creditsId}: + get: + operationId: getCredit + summary: Get Billing Credit + description: Requires the `billing-credits-view` capability. + tags: + - Credits + parameters: + - name: creditsId + description: The ID for a given credit. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a credit resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Credit' + default: + $ref: '#/components/responses/DefaultError' + /v1/changelog: + get: + operationId: getChangelog + tags: + - Changelog + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + summary: Get Changelog + description: Requires the `platform-changelog-view` capability. + responses: + '200': + description: Returns an array of changelog entries. + content: + application/json: + schema: + title: ListChangelogReturn + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ChangelogEntry' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/invoices: + get: + operationId: getInvoices + summary: List Billing Invoices + description: | + List the Invoices assoicated with the Hub. + + Requires the `billing-invoices-view` capability. + tags: + - Invoices + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - due + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + search: + type: string + description: | + `filter[search]=value` search for the specified text on supported fields. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the invoice's current state. + range-start: + description: The start date from when to pull the invoices + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull the invoices + $ref: '#/components/schemas/DateTime' + responses: + '200': + description: Returns a list of Invoices. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Invoice' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/invoices/{invoiceId}: + get: + operationId: getInvoice + summary: Get Billing Invoice + description: Requires the `billing-invoices-view` capability. + tags: + - Invoices + parameters: + - name: invoiceId + description: The ID of the invoice. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - due + - hub + - name: token + in: query + required: false + description: Token can be optionally provided for authentication outside of the hub context. + schema: + type: string + responses: + '200': + description: Returns an invoice resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Invoice' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/invoices/{invoiceId}/tasks: + post: + operationId: createInvoiceJob + summary: Create Invoice Job + description: | + Creates a new job for an Invoice. Generally used to make a payment on an invoice. + + Requires the `billing-invoices-pay` capability. + tags: + - Invoices + parameters: + - name: invoiceId + description: The ID of the invoice. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + enum: + - pay + description: The name of the action to perform. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/methods: + get: + operationId: getBillingMethods + tags: + - Methods + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + summary: List Billing Methods + description: | + Lists the Billing Methods associated with the Hub defined in X-Hub-ID. + + Requires the `billing-methods-manage` capability. + responses: + '200': + description: returns a collection of billing methods. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Method' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createBillingMethod + tags: + - Methods + parameters: [] + summary: Create Billing Method + description: Requires the `billing-methods-manage` capability. + requestBody: + description: Parameters for creating a new billing method. + content: + application/json: + schema: + type: object + required: + - name + - primary + - address + properties: + name: + type: string + description: A name for the billing method. + primary: + type: boolean + description: A boolean where true represents a billing method being primary. + address: + $ref: '#/components/schemas/Address' + credit_card: + oneOf: + - type: object + required: + - name + - number + - cvv + - expiration + properties: + name: + type: string + number: + type: string + cvv: + type: string + expiration: + type: object + required: + - month + - year + properties: + month: + type: number + year: + type: number + - type: 'null' + us_bank_acct: + oneOf: + - type: object + required: + - account_holder_name + - account_holder_type + - routing_number + - account_number + properties: + account_holder_name: + type: string + description: The name of the account holder. + account_holder_type: + type: string + description: Whether this account is owned by a business or an individual. + enum: + - individual + - company + routing_number: + type: string + description: The routing number of the bank where the account lives. + account_number: + type: string + description: The number of the bank account. + - type: 'null' + direct_payment: + oneOf: + - type: object + description: Only available for hubs that have direct billing enabled. Contact Cycle staff at support@cycle.io for any questions. + required: + - preference + - instructions + properties: + preference: + type: string + description: The preference for how the payment will be sent. + enum: + - check + - wire + - ach + instructions: + type: string + description: Any additional instructions for an organization's billing dept., etc. that should be known about this payment method. + - type: 'null' + responses: + '201': + description: Returns a billing method. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Method' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/methods/{methodId}: + get: + operationId: getBillingMethod + summary: Get Billing Method + description: Requires the `billing-methods-manage` capability. + tags: + - Methods + parameters: + - name: methodId + description: The ID of the billing method. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a billing method resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Method' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateBillingMethod + summary: Update Billing Invoice + description: Requires the `billing-methods-manage` capability. + tags: + - Methods + parameters: + - name: methodId + description: The ID of the billing method. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name for the billing method. + primary: + type: boolean + description: A boolean where true represents a billing method being primary. + responses: + '200': + description: Returns a billing method resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Method' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteBillingMethod + summary: Delete Biilling Method + description: | + Deletes the Billing Method. However, the primary payment method may not be deleted. + Requires the `billing-methods-manage` capability. + tags: + - Methods + parameters: + - name: methodId + description: The ID of the billing method. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/methods/{methodId}/tasks: + post: + operationId: createBillingMethodJob + summary: Create Billing Method Job + description: | + Creates a new job for a billing method. Generally used to verify a payment method. + + Requires the `billing-methods-manage` capability. + tags: + - Methods + parameters: + - name: methodId + description: The ID of the method. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - verify + description: The name of the action to perform. + contents: + type: object + required: + - micro_deposits + properties: + micro_deposits: + type: array + items: + type: integer + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/orders: + get: + operationId: getOrders + summary: List Billing Orders + description: Requires the `billing-services-manage` capability. + tags: + - Orders + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + - name: meta + in: query + required: false + schema: + type: array + items: + type: string + enum: + - due + - $ref: '#/components/parameters/OrderIncludeParam' + responses: + '200': + description: Returns a list of Billing Orders. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Order' + includes: + $ref: '#/components/schemas/BillingOrderIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createOrder + summary: Create Billing Order + description: Requires the `billing-orders-manage` capability. + tags: + - Orders + parameters: + - name: meta + in: query + required: false + schema: + type: array + items: + type: string + enum: + - due + - $ref: '#/components/parameters/OrderIncludeParam' + requestBody: + description: Parameters for creating a new order + content: + application/json: + schema: + type: object + properties: + tier_plan_id: + type: string + description: ID associated with the tier plan + support_plan_id: + type: string + description: ID associated with the support plan + term_length: + type: string + description: String that defines term length + enum: + - once + - monthly + - yearly + promo_code: + type: string + description: String that defines a promo code + responses: + '201': + description: Returns a Billing Order. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/BillingOrder' + includes: + $ref: '#/components/schemas/BillingOrderIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/orders/{orderId}: + get: + operationId: getBillingOrder + summary: Get Billing Order + description: Requires the `billing-services-manage` capability. + tags: + - Orders + parameters: + - name: orderId + description: The ID of the billing order. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + schema: + type: array + items: + type: string + enum: + - due + - $ref: '#/components/parameters/OrderIncludeParam' + responses: + '200': + description: Returns a Billing Order + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Order' + includes: + $ref: '#/components/schemas/BillingOrderIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateBillingOrder + summary: Update Billing Order + description: Requires the `billing-services-manage` capability. + tags: + - Orders + parameters: + - name: orderId + description: The ID of the billing order. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + schema: + type: array + items: + type: string + enum: + - due + - $ref: '#/components/parameters/OrderIncludeParam' + requestBody: + content: + application/json: + schema: + type: object + properties: + tier_plan_id: + type: string + description: ID associated with the tier plan + support_plan_id: + type: string + description: ID associated with the support plan + term_length: + type: string + description: String that defines term length + enum: + - once + - monthly + - yearly + promo_code: + type: string + description: String that defines a promo code + responses: + '200': + description: Returns a Billing Order. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Order' + includes: + $ref: '#/components/schemas/BillingOrderIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/orders/{orderId}/tasks: + post: + operationId: createOrderJob + summary: Create Billing Order Job + description: | + Used to confirm a Billing Order. + + Requires the `billing-services-manage` capability. + tags: + - Orders + parameters: + - name: orderId + description: The ID of the requested Order + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + enum: + - confirm + description: The name of the action to perform + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/plans/support: + get: + operationId: getBillingSupportPlans + summary: List Support Plans + tags: + - Plans + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + deprecated: true + responses: + '200': + description: Returns available support plans. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/SupportPlan' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/plans/tiers: + get: + operationId: getBillingTiers + summary: List Billing Tiers + description: Returns list of availiable Billing Tiers. + tags: + - Plans + parameters: [] + responses: + '200': + description: Returns a list of available Billing Tiers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/TierPlan' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/services: + get: + operationId: getBillingServices + summary: List Billing Services + description: Requries the `billing-services-view` capability. + tags: + - Services + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Billing Services. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/BillingService' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/services/{servicesId}: + get: + operationId: getBillingService + summary: Get Billing Service + description: Requries the `billing-services-view` capability. + tags: + - Services + parameters: + - name: servicesId + description: The ID of the Billing Service. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns the Hub's specified Billing Service. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/BillingService' + default: + $ref: '#/components/responses/DefaultError' + /v1/billing/services/overages: + get: + operationId: getBillingOverages + summary: List Billing Overages + tags: + - Services + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns Billing Overages. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Overage' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers: + get: + operationId: getContainers + summary: List Containers + description: Requires the `containers-view` capability. + tags: + - Containers + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - instances_count + - domains + - ips + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - images + - stack_builds + - stacks + - environments + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + creator: + type: string + description: | + `filter[creator]=account-ID` filter for containers matching a particular creator, such as `account-ID` or `environment-ID` + identifier: + type: string + description: | + `filter[identifier]=value` List only those containers matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search containers for a value associated with a field on the given container(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the container's current state. + deprecated: + type: string + description: | + `filter[deprecated]=true` filter for containers that are deprecated. + service: + type: string + description: | + `filter[service]=value` service filtering will allow you to filter by service type: `loadbalancer`, `discovery`, `vpn`. + public_network: + type: string + description: | + `filter[public_network]=value` public network filtering will allow you to filter by the containers network settings: `enabled`, `disabled`, `egress-only`, `environment-limited`. + image: + type: string + description: | + `filter[image]=ID` image filtering by ID. Submit the ID of the image you wish to filter for and the return will be any containers currently using the image. + environment: + type: string + description: | + `filter[environment]=ID` environment filtering by ID. Submit the ID of the environment you wish to filter for and the return will be any containers in that environment. + tags: + type: string + description: | + `filter[tags]=tagone,tagtwo,tagthree` container filtering using server tags. If the container has the tags you submit it will be part of the return. + stack: + type: string + description: | + `filter[stack]=ID` stack filtering by ID. Submit the ID of the stack you wish to filter for and the return will be any containers deployed associated with 'containers' from the stack. + deployment: + type: string + description: | + `filter[deployment]=v1,v2` filter containers by deployment(s). + range-start: + description: The start date from when to pull the containers + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull the containers + $ref: '#/components/schemas/DateTime' + deployment_strategy: + type: string + description: | + `filter[deployment_strategy]=strategy` deployment strategy filtering by strategy string. Submit the deployment strategy (example: "function") of the strategy you wish to filter for and the return will be any containers matching that description. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Containers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Container' + includes: + $ref: '#/components/schemas/ContainerIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createContainer + summary: Create Container + description: Requires the `containers-deploy` capability. + tags: + - Containers + parameters: [] + requestBody: + description: Parameters for creating a new Container. + content: + application/json: + schema: + type: object + required: + - name + - environment_id + - image_id + - stateful + - config + properties: + name: + type: string + description: A user defined name for the Container. + identifier: + anyOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + environment_id: + type: string + description: An identifier for the Environment this Container will be deployed to. + image_id: + type: string + description: An identifier for the Image used to create this Container. + stateful: + type: boolean + description: A boolean where true represents this Container is stateful. + config: + $ref: '#/components/schemas/Config' + lock: + type: boolean + description: When set to true, prevents this Container from being deleted. + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + volumes: + type: array + items: + $ref: '#/components/schemas/ContainerVolume' + annotations: + description: Custom meta data. Not utilized by Cycle. + oneOf: + - type: object + additionalProperties: {} + - type: 'null' + responses: + '201': + description: Returns a Container. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Container' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}: + get: + operationId: getContainer + summary: Get Container + description: | + Gets a Container. + + Requires the `containers-view` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested Container. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - instances_count + - domains + - ips + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - images + - stack_builds + - stacks + - environments + responses: + '200': + description: Returns a Container. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Container' + includes: + $ref: '#/components/schemas/ContainerIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateContainer + summary: Update Container + description: | + Updates the specified Container. + + Requires the `containers-manage` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the Container. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a Container. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The name for the Container. + identifier: + type: string + description: The name for the identifier. + deprecate: + type: boolean + description: Sets whether Container should be deprecated. + lock: + type: boolean + description: When set to true, prevents this Container from being deleted. + annotation: + type: object + description: User meta data for the Container. + additionalProperties: + type: string + responses: + '200': + description: Returns the updated Container. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Container' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteContainer + summary: Delete Container + description: Requires the `containers-manage` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested Container. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/summary: + get: + operationId: getContainerSummary + summary: Get Container Summary + description: Requires the `containers-view` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns an Container summary resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + description: Contains useful and relevant data/statistics for a container that would otherwise be several separate API calls. + required: + - id + - state + properties: + id: + $ref: '#/components/schemas/ID' + state: + $ref: '#/components/schemas/ContainerState' + stats: + anyOf: + - $ref: '#/components/schemas/StateCountSummary' + - type: 'null' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/tasks: + post: + operationId: createContainerJob + summary: Create Container Job + description: | + Used to perform different actions on a given Container. + + Requires the following capabilities based on the task: + `start`: `containers-manage` + `stop`: `containers-manage` + `restart`: `containers-manage` + `reconfigure`: `containers-manage` + `volumes.reconfigure`: `containers-volumes-manage` + `reimage`: `containers-manage` + `scale`: `containers-manage` + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new container job. + content: + application/json: + schema: + $ref: '#/components/schemas/ContainerTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/servers: + get: + operationId: getContainerServers + summary: List Container Servers + description: | + Lists all Servers that currently have an Instance of this Container deployed to them. + + Requires the `containers-view` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - primary_ip + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns an array of Server IDs / number of Instances of this Container deployed to them. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ServerInstancesSummary' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/servers/usable: + get: + operationId: getCompatibleServers + tags: + - Containers + summary: List Compatible Servers + description: | + Gets a list of servers that are compatible with the specified Container and its restrictions (tags, etc). + + Requires the `containers-view` capability. + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - node + - instances_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - location + - models + - integrations + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Servers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Server' + includes: + $ref: '#/components/schemas/ServerIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/compatible-images: + get: + operationId: getCompatibleImages + summary: Get Compatible Images + description: | + Returns a list of Images that are compatible with the specified Container. + Used to quickly find Images that can be used for reimaging the Container. + + Requires the `containers-view` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested Container. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of compatible Images. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Image' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances: + get: + operationId: getInstances + summary: List Instances + description: Requires the `containers-view` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the container this instance is created from. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + explode: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - servers + - locations + - integrations + - containers + - environments + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - node + - sdn_pool_ips + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the instance's current state. + search: + type: string + description: | + `filter[search]=value` search instances for a value associated with a field on the given instance(s). + server: + type: string + description: | + `filter[server]=ID` server filtering by ID. Submit the ID of the server you wish to filter for and the return will be any instances of the container currently deployed to the given server. + range-start: + description: The start date from when to pull the instances + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull the instances + $ref: '#/components/schemas/DateTime' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Container Instances. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + includes: + $ref: '#/components/schemas/InstanceIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createInstances + summary: Create Instances + description: | + Manually create Instances of a Container. + + Requires the `containers-update` capability. + tags: + - Containers + - Instances + parameters: + - name: containerId + description: The ID of the Container this Instance is created from. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: array + items: + type: object + required: + - server_id + - new_instances + properties: + server_id: + type: string + description: The ID of the Server the new Instance(s) should be deployed to. + new_instances: + type: integer + description: The number of new Instances to be created on the given Server. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteContainerInstances + summary: Delete Container Instance(s) + description: | + Manually delete Instances of a Container. + + Requires the `containers-update` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the container the instance(s) were created from. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}: + get: + operationId: getInstance + summary: Get Instance + description: Requires the `containers-view` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - node + - sdn_pool_ips + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - servers + - locations + - integrations + - containers + - environments + responses: + '200': + description: Returns a Container Instance. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Instance' + includes: + $ref: '#/components/schemas/InstanceIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteInstance + summary: Delete Container Instance + description: Requires the `containers-update` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/ssh: + get: + operationId: generateInstanceSSHCredentials + summary: Generate Instance SSH Credentials + description: | + Generates credentials for connecting to an Instance via SSH. The generated endpoint/secret can be used to log in via SSH + into the Instance without exposing ports on the container or host. + + Requires the `containers-ssh` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns an SSH connection response. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/SSHResponse' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: expireInstanceSSHCredentials + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + summary: Expire SSH Credentials + description: | + Instantly expires any SSH credentials generated for this Instance. + + Requires the `containers-ssh` capability. + responses: + '200': + description: Returns the number of tokens removed. + content: + application/json: + schema: + title: ExpireSSHTokenResponse + type: object + required: + - data + properties: + data: + type: object + description: The number of tokens expired. + required: + - tokens + properties: + tokens: + type: integer + description: The number of tokens expired. + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/tasks: + post: + operationId: createInstanceJob + summary: Create Instance Job + description: | + Used to perform different actions on a given Container Instance. Can be used to migrate or undo a migration of a Container Instance. + + Requires the `containers-instance-migrate` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new container instance job. + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/volumes: + get: + operationId: getInstanceVolumes + summary: List Instance Volumes + description: Requires the `containers-view` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested Container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the Container Instance. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Container Instance Volumes. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/InstanceVolume' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/telemetry/resources/report: + get: + operationId: getInstanceTelemetryReport + summary: Get Instance Telemetry Report + description: | + Retrieves a point-in-time report of an Instance's resource usage (CPU, RAM, Network, Storage, etc). + + Requires the `containers-view` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the container instance. + in: path + required: true + schema: + type: string + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + range-start: + description: The start date from when to pull instance telemetry data + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull instance telemetry data + $ref: '#/components/schemas/DateTime' + responses: + '200': + description: Returns an Instance telemetry report. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/InstanceTelemetryReport' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/telemetry/resources/stream: + get: + operationId: getInstanceTelemetryStreamAuth + summary: Instance Telemetry Stream Authorization + description: | + Retrieves an access token and URL to open a websocket to for streaming instance telemetry live. + This connects directly to the compute layer on the server the instance is hosted on, and streams telemetry in real time. + + Requires the `containers-view` capability. + tags: + - Instances + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: instanceId + description: The ID for the Container Instance. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns credentials for connecting to an instance telemetry stream. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + description: Credentials for connecting to the instance telemetry stream on compute. + required: + - token + - address + properties: + token: + type: string + description: The authentication token passed into the address as a URL parameter (?token). + address: + description: The URL address to open a websocket to for streaming instance telemetry data. + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/instances/{instanceId}/console: + get: + operationId: getInstanceConsoleStreamAuth + summary: Instance Console Stream Authorization + description: | + Returns the authorization information necessary to connect to a Container Instance's console. + To connect via WebSocket, use the returned address, and append the returned token as a URL parameter: `
?token=`. + + Requires the `containers-console` capability. + tags: + - Instances + parameters: + - name: containerId + in: path + required: true + description: The ID for the Container + schema: + type: string + - name: instanceId + in: path + required: true + description: The ID of the Instance. + schema: + type: string + responses: + '200': + description: Returns authorization information necessary for accessing a Container Instance's console. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + title: InstanceConsoleAuth + type: object + required: + - token + - address + properties: + token: + type: string + description: A token used for connecting to the Instance console. + address: + type: string + description: The protocol and url for connecting to the Instance console. + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/functions/tasks: + post: + operationId: createFunctionJob + summary: Create Function Job + description: | + Used to perform different actions on a given Function Container. + + Requires the `containers-functions-trigger` capability. + tags: + - Containers + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new container function job. + content: + application/json: + schema: + $ref: '#/components/schemas/FunctionTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/backups: + get: + operationId: getContainerBackups + summary: List Container Backups + description: Requires the `containers-backups-view` capability. + tags: + - Backups + parameters: + - name: containerId + description: The ID of the requested Container. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of container backup resources. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ContainerBackup' + includes: + $ref: '#/components/schemas/ContainerBackupIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/backups/{backupId}: + get: + operationId: getContainerBackup + summary: Get a specific Container Backup + description: | + Gets the specified Container Backup. + + Requires the `containers-backups-view` capability. + tags: + - Backups + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: backupId + description: The ID for the container backup. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + responses: + '200': + description: Returns a Container Backup. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ContainerBackup' + includes: + $ref: '#/components/schemas/ContainerBackupIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteContainerBackup + summary: Delete Container Backup + description: Requires the `containers-backups-manage` capability. + tags: + - Backups + parameters: + - name: containerId + description: The ID of the container. + in: path + required: true + schema: + type: string + - name: backupId + description: The ID of the container backup. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/backups/{backupId}/tasks: + post: + tags: + - Backups + operationId: createContainerBackupJob + summary: Create Container Backup Job + description: | + Creates a Container Backup Job. + Can be used to restore a Container Backup for a given Container Instance. + + Requires the `containers-backups-manage` capability. + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: backupId + description: The ID of the backup. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - restore + description: The action to take. + contents: + type: object + description: Additional information the platform needs to create this Job. + required: + - instance_id + properties: + instance_id: + type: string + description: The ID of the instance this Container Backup is being restored to. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/containers/{containerId}/backups/{backupId}/logs: + get: + operationId: getContainerBackupLogs + summary: List Container Backup Logs + description: Requires the `containers-backups-view` capability. + tags: + - Backups + parameters: + - name: containerId + description: The ID of the requested container. + in: path + required: true + schema: + type: string + - name: backupId + description: The ID for the container backup. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a collection of Container Backup Logs. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ContainerBackupLogs' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones: + get: + operationId: getDNSZones + summary: List DNS Zones + description: Requires the `dns-view` capability. + tags: + - Zones + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the DNS Zone's current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a collection of DNS Zones. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/DnsZone' + includes: + $ref: '#/components/schemas/DnsZoneIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createDNSZone + tags: + - Zones + parameters: [] + summary: Create DNS Zone + description: Requires the `dns-manage` capability. + requestBody: + description: Parameters for creating a new DNS Zone. + content: + application/json: + schema: + type: object + required: + - hosted + - origin + properties: + hosted: + type: boolean + description: A boolean where true represents the desire for the origin to be of the type `hosted`. + origin: + type: string + description: The origin that will be created. + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '201': + description: Returns the DNS Zone resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsZone' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}: + get: + operationId: getDNSZone + summary: Get DNS Zone + description: Requires the `dns-view` capability. + tags: + - Zones + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a DNS zone resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsZone' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateDNSZone + summary: Update DNS Zone + description: Requires the `dns-manage` capability. + tags: + - Zones + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + requestBody: + description: Parameters for updating a DNS Zone. + content: + application/json: + schema: + type: object + properties: + hosted: + type: + - boolean + - 'null' + description: A boolean where true represents the desire for the origin to be of the type `hosted`. + responses: + '200': + description: Returns a DNS zone resource. + content: + application/json: + schema: + title: DNSZoneUpdateResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsZone' + includes: + $ref: '#/components/schemas/DnsZoneIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteDNSZone + summary: Delete DNS Zone + description: Requires the `dns-manage` capability. + tags: + - Zones + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}/access: + patch: + operationId: updateDNSZoneAccess + summary: Update DNS Zone Access + description: Requires the `dns-manage` capability, and if an ACL is present, the `manage` privilege. + tags: + - Zones + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + requestBody: + description: Parameters for updating a DNS Zone. + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns a DNS zone. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsZone' + includes: + $ref: '#/components/schemas/DnsZoneIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}/tasks: + post: + operationId: createDNSZoneJob + summary: Create DNS Zone Job + description: | + Used to perform different actions on a given DNS zone. + + Requires the `dns-manage` capability. + tags: + - Zones + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new DNS zone job. + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + description: The action that the job will take. + enum: + - verify + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}/records: + get: + operationId: getDNSZoneRecords + summary: List DNS Zone Records + description: Requires the `dns-view` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/RecordIncludeParam' + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the DNS record's current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a collection of DNS Zone Records. + content: + application/json: + schema: + title: DNSZoneRecordListReturn + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/DnsRecord' + includes: + $ref: '#/components/schemas/RecordIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createDNSZoneRecord + summary: Create DNS Zone Record + description: Requires the `dns-manage` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the Zone. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/RecordIncludeParam' + requestBody: + description: Parameters for creating a new DNS Zone Record. + content: + application/json: + schema: + type: object + required: + - type + - name + properties: + type: + $ref: '#/components/schemas/DnsRecordTypes' + name: + type: string + description: A name for the given record where `@` represents the desire to use the root of the origin. + responses: + '201': + description: Returns the DNS zone resource. + content: + application/json: + schema: + title: DNSZoneCreateResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsRecord' + includes: + $ref: '#/components/schemas/RecordIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}/records/{recordId}: + get: + operationId: getDnsRecord + summary: Get DNS Zone Record + description: Requires the `dns-manage` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the Zone. + in: path + required: true + schema: + type: string + - name: recordId + description: The ID of the record. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/RecordIncludeParam' + responses: + '200': + description: Returns a DNS Zone Record. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsRecord' + includes: + $ref: '#/components/schemas/RecordIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateDNSZoneRecord + summary: Update DNS Zone Record + description: Requires the `dns-manage` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the Zone. + in: path + required: true + schema: + type: string + - name: recordId + description: The ID of the record. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/RecordIncludeParam' + requestBody: + description: Parameters for updating a DNS Zone Record. The name value cannot be updated and is omitted from the properties. + content: + application/json: + schema: + type: object + required: + - type + properties: + type: + $ref: '#/components/schemas/DnsRecordTypes' + responses: + '200': + description: Returns a DNS Zone Record. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/DnsRecord' + includes: + $ref: '#/components/schemas/RecordIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteDNSZoneRecord + summary: Delete DNS Zone Record + description: Requires the `dns-manage` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the Zone. + in: path + required: true + schema: + type: string + - name: recordId + description: The ID of the DNS Zone Record. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/zones/{zoneId}/records/{recordId}/tasks: + post: + operationId: createDNSZoneRecordJob + summary: Create a DNS Zone Record Job + description: | + Used to perform different actions on a given DNS Zone record. + + Requires the `dns-manage` capability. + tags: + - Records + parameters: + - name: zoneId + description: The ID of the zone. + in: path + required: true + schema: + type: string + - name: recordId + description: The ID of the record. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new DNS Zone Record Job. + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + description: The action that the job will take. + enum: + - cert.generate + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/attempts: + get: + operationId: getTLSGenerationAttempts + summary: List TLS Generation Attempts + description: Requires the `dns-view` capability. + tags: + - TLS + parameters: + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + domain: + type: string + description: | + `filter[domain]=value` filter the return for TLS attempts by domain. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of TLS certificate generation attempts. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Attempt' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/certificates: + get: + operationId: getAllTlsCertificates + summary: List all TLS Certificates whether user generated or automatically generated by the platform. + description: | + Retrieve a list of TLS certificates. + + Requires the `dns-certs-view` capability. + tags: + - TLS + parameters: + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + domain: + type: string + description: | + `filter[domain]=value1` filter user certificates by associated domain. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow filtering by the current state. + user-supplied: + type: string + description: | + `filter[user-supplied]=true` List only those certificates that are user supplied. + `filter[user-supplied]=false` List only those certificates that are auto generated. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a TLS certificate. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/TlsCertificate' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/certificates/lookup: + get: + operationId: lookupTLSCertificate + summary: Lookup TLS Certificate + description: | + Lookup and retrieve a TLS certificate bundle for a specified domain. + + If the `private` parameter is set to `true`, the private key, bundle, and/or CSR will be included. Including these private fields requires the `dns-certs-view` capability. + tags: + - TLS + parameters: + - name: domain + in: query + style: form + required: true + description: The domain to lookup. + schema: + type: string + - name: private + in: query + style: form + required: false + description: If true, will include the private key, bundle, and/or CSR for this certificate. Requires the `dns-certs-view` capability. + schema: + type: boolean + responses: + '200': + description: Returns a TLS certificate bundle if available. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + allOf: + - $ref: '#/components/schemas/TlsCertificate' + - type: object + properties: + private_key: + type: string + bundle: + type: string + csr: + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/certificates/user-supplied: + get: + operationId: getUserSuppliedCertificates + summary: List User Supplied TLS Certificates + description: | + Retrieve a list of TLS certificates that were uploaded to Cycle. + + Requires the `dns-certs-view` capability. + tags: + - TLS + parameters: + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + domain: + type: string + description: | + `filter[domain]=value1` filter user certificates by associated domain. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow filtering by the current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a TLS certificate. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/TlsCertificate' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: uploadUserSuppliedCertificate + tags: + - TLS + parameters: [] + summary: Upload User Supplied TLS Certificate + description: | + Upload a user-supplied TLS certificate to the hub. This TLS certificate can be utilized by **LINKED** records matching the specified domains. + + Requires the `dns-manage` capability. + requestBody: + description: Parameters for creating a new TLS certificate. + content: + application/json: + schema: + type: object + required: + - private_key + - bundle + properties: + private_key: + type: string + description: The certificate's private key. + bundle: + type: string + description: A PEM encoded certificate bundle. + responses: + '201': + description: Returns a TLS certificate. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/TlsCertificate' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/certificates/user-supplied/{certificateId}: + get: + operationId: getUserSuppliedCertificate + summary: Get User Supplied TLS Certificate + description: | + Gets a list of custom TLS certificates uploaded to the hub. + + Requires the `dns-certs-view` capability. + tags: + - TLS + parameters: + - name: certificateId + description: The ID of the TLS certificate. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a TLS certificate. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/TlsCertificate' + default: + $ref: '#/components/responses/DefaultError' + /v1/dns/tls/certificates/user-supplied/{certificateId}/tasks: + post: + operationId: createUserSuppliedCertificateJob + summary: Create User Supplied TLS Certificate Job + description: | + Used to perform different actions on a given user supplied TLS certificate. + + Requires the `dns-manage` capability. + tags: + - TLS + parameters: + - name: certificateId + description: The ID of the TLS certificate. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new TLS certificate job. + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + description: | + The action that the job will take. + + **deprecate**: Cycle will deprecate this certificate, and try to find another usable certificate. If none exists, it will generate a new one + for the applicable domains. + enum: + - deprecate + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments: + get: + operationId: getEnvironments + summary: List Environments + description: Requires the `environments-view` capability. + tags: + - Environments + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - containers_count + - instances_count + - service_versions + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - stacks + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + creator: + type: string + description: | + `filter[creator]=account-ID` filter for environments matching a particular creator, such as `account-ID`. + identifier: + type: string + description: | + `filter[identifier]=value` List only those environments matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given environment(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the environment's current state. + stack_build: + type: string + description: | + `filter[stack_build]=ID` stack build filtering by ID. Submit the ID of the stack build you wish to filter for and the return sill be any environments that have the stack build deployed to them. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Environments. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Environment' + includes: + type: object + properties: + creators: + $ref: '#/components/schemas/CreatorInclude' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createEnvironment + summary: Create Environment + description: Requires the `environments-create` capability. + tags: + - Environments + parameters: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - name + - cluster + - about + - features + - stack + properties: + name: + type: string + description: A user defined name for the Environment. + identifier: + oneOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + cluster: + type: string + description: The cluster this Environment is associated with. + about: + type: object + description: Contains details regarding the Environment. + required: + - description + properties: + description: + type: string + description: A custom description for this Environment. + features: + $ref: '#/components/schemas/EnvironmentFeatures' + responses: + '201': + description: Returns an Environment. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Environment' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}: + get: + operationId: getEnvironment + summary: Get Environment + description: Requires the `environments-view` capability. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested environment. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - containers_count + - instances_count + - service_versions + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - stacks + - clusters + responses: + '200': + description: Returns an Environment. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Environment' + includes: + type: object + properties: + creators: + $ref: '#/components/schemas/CreatorInclude' + clusters: + $ref: '#/components/schemas/ClusterIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateEnvironment + summary: Update Environment + description: | + Updates the specificed Environment. + + Requires the `environments-manage` capability. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating an Environment. + content: + application/json: + schema: + type: object + properties: + name: + type: + - string + - 'null' + identifier: + type: + - string + - 'null' + version: + type: + - string + - 'null' + about: + anyOf: + - $ref: '#/components/schemas/EnvironmentAbout' + - type: 'null' + responses: + '200': + description: Returns an Environment. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Environment' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteEnvironment + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + summary: Delete Environment + description: Requires the `environments-manage` capability. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/access: + patch: + operationId: updateEnvironmentAccess + summary: Update Environment Access + description: | + Updates the specificed Environment. + + Requires the `environments-manage` capability. If an ACL is present, requires the `manage` privilege. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating an Environment. + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns an Environment. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Environment' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/tasks: + post: + operationId: createEnvironmentJob + summary: Create Environment Job + description: | + Create a job for an Environment, such as 'start' or 'stop'. + + Requires the `environments-manage` capability. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new Environment job. + content: + application/json: + schema: + $ref: '#/components/schemas/EnvironmentTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/summary: + get: + operationId: getEnvironmentSummary + summary: Get Environment Summary + description: | + Gets the summary of an Environment. Contains useful and relevant data/statistics that would otherwise be several separate API calls. + + Requires the `environments-view` capability. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the requested environment. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns an environment summary object. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/EnvironmentSummary' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/deployments: + get: + operationId: getEnvironmentDeployments + summary: List Environment Deployments + description: | + Gets a list of all deployments in the specified Environment. + + Requires the `environments-view` capability. + tags: + - Deployments + parameters: + - name: environmentId + description: The ID of the Environment to get the list of deployments for. + in: path + required: true + schema: + type: string + responses: + '200': + description: A list of deployments. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - versions + properties: + versions: + type: object + description: A map where the key is the version property of a deployment. + additionalProperties: + type: object + required: + - containers + - tags + properties: + tags: + type: array + description: An array of all tags on this environment that point to this version. + items: + $ref: '#/components/schemas/Identifier' + containers: + type: integer + description: The number of containers utilizing this version of this deployment. + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/export/stack: + post: + operationId: exportStack + summary: Export As Stack + description: | + Exports an environment as a stack file for reuse. + + Requires the `environments-manage` capability. You must also have management permissions on the target environment ACL. + tags: + - Environments + parameters: + - name: environmentId + description: The ID of the target environment. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + include: + type: object + description: | + Controls which top-level resources from the environment are included in the exported stack. + Any option left unset defaults to `false`. + properties: + services: + type: boolean + default: false + description: When true, includes the environment's service containers (e.g. discovery, load balancer, VPN) in the export. + scoped_variables: + type: boolean + default: false + description: When true, includes the environment's scoped variables in the export. + containers: + type: boolean + default: false + description: When true, includes the environment's containers in the export. + render: + type: object + description: | + Controls how included resources are rendered into the stack - i.e. how image origins are resolved + and how much detail is inlined for each resource type. + properties: + scoped_variables: + type: object + description: Render options applied to scoped variables included in the export. + properties: + include_secrets: + type: boolean + default: false + description: | + When true, the secret values of included scoped variables are resolved and inlined into the export. + By default secrets are not included, and only the variable definitions are exported. + images: + type: object + description: Render options applied to images referenced by the export. + properties: + resolve_origins: + type: boolean + default: false + description: | + When set to true, Cycle will resolve image origins and inline them into the stack, essentially making this stack portable outside the hub it's currently used in. + By default, this is set to false, and the export will just reference existing image sources used by this stack in your hub by ID. + containers: + type: object + description: Render options applied to containers included in the export. + properties: + include_deployments: + type: array + description: | + Defines which deployment containers to include in the stack export. By default, no containers tagged in a deployment are exported. + This option includes all containers with the specified deployment tags in the final output, in addition to the containers that are not part of any deployment. + items: + type: string + responses: + '200': + description: Returns a stack spec file. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/StackSpec' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/scoped-variables: + get: + operationId: getScopedVariables + summary: List Scoped Variables + description: Requires the `scoped-variables-view` capability. + tags: + - Scoped Variables + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + - name: filter + in: query + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those scoped variables matching this identifier. May return multiple results. + container: + type: string + description: | + `filter[container]=value` List only those scoped variables assigned to the specified container ID. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given scoped variable(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the scoped variable's current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of scoped variables. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ScopedVariable' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createScopedVariable + summary: Create Scoped Variable + description: Requires the `scoped-variables-manage` capability. + tags: + - Scoped Variables + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a Scoped Variable. + content: + application/json: + schema: + type: object + required: + - identifier + - scope + - source + properties: + identifier: + type: string + description: An identifier for this Scoped Variable. + scope: + $ref: '#/components/schemas/ScopedVariableScope' + access: + $ref: '#/components/schemas/ScopedVariableAccess' + source: + type: object + description: The source or value of the Scoped Variable. + discriminator: + propertyName: type + mapping: + raw: '#/components/schemas/RawSource' + url: '#/components/schemas/URLSource' + oneOf: + - $ref: '#/components/schemas/RawSource' + - $ref: '#/components/schemas/URLSource' + deployment: + anyOf: + - $ref: '#/components/schemas/Deployment' + - type: 'null' + responses: + '201': + description: Returns a Scoped Variable. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ScopedVariable' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/scoped-variables/{scopedVariableId}: + get: + operationId: getScopedVariable + summary: Get Scoped Variable + description: Requires the `scoped-variables-view` capability. + tags: + - Scoped Variables + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + - name: scopedVariableId + description: The ID of the requested Scoped Variable. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a Scoped Variable. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ScopedVariable' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateScopedVariable + summary: Update Scoped Variable + description: Requires the `scoped-variables-manage` capability. + tags: + - Scoped Variables + parameters: + - name: environmentId + description: The ID of the requested endpointnvironment. + in: path + required: true + schema: + type: string + - name: scopedVariableId + description: The ID of the requested Scoped Variable. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a Scoped Variable. + content: + application/json: + schema: + type: object + properties: + identifier: + type: string + description: An identifier, similar to a key in an Environment variable. Its used when envoking the Scoped Variable. + scope: + $ref: '#/components/schemas/ScopedVariableScope' + access: + $ref: '#/components/schemas/ScopedVariableAccess' + source: + type: object + description: The source or value of the Scoped Variable. + discriminator: + propertyName: type + mapping: + raw: '#/components/schemas/RawSource' + url: '#/components/schemas/URLSource' + oneOf: + - $ref: '#/components/schemas/RawSource' + - $ref: '#/components/schemas/URLSource' + responses: + '200': + description: Returns a Scoped Variable. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ScopedVariable' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteScopedVariable + summary: Delete Scoped Variable + description: Requires the `scoped-variables-manage` capability. + tags: + - Scoped Variables + parameters: + - name: environmentId + description: The ID of the requested Environment. + in: path + required: true + schema: + type: string + - name: scopedVariableId + description: The ID of the requested Scoped Variable. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/discovery/tasks: + post: + operationId: createDiscoveryServiceJob + summary: Create Discovery Service Job + description: Creates a task that will update the discovery service's configuration. + tags: + - Services/Discovery + parameters: + - name: environmentId + description: The ID of the environment where this discovery service resides. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for reconfiguring a discovery service. + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - reconfigure + description: The name of the action to perform. + contents: + type: object + properties: + config: + anyOf: + - $ref: '#/components/schemas/DiscoveryConfig' + - type: 'null' + high_availability: + type: + - boolean + - 'null' + description: A boolean where `true` represents the desire to run the environment discovery service in high availability mode. + auto_update: + type: + - boolean + - 'null' + description: A boolean where `true` represents the desire to automatically update the environment discovery service. + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/gateway/tasks: + post: + operationId: createGatewayServiceJob + summary: Create Gateway Service Job + description: Creates a task that will update the gateway service's configuration. + tags: + - Services/Gateway + parameters: + - name: environmentId + description: The ID of the environment where this gateway service resides. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for reconfiguring a gateway service. + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - reconfigure + description: The name of the action to perform. + contents: + type: object + properties: + auto_update: + type: + - boolean + - 'null' + description: A boolean where `true` represents the desire to automatically update the environment gateway service. + config: + anyOf: + - $ref: '#/components/schemas/GatewayConfig' + - type: 'null' + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/lb: + get: + operationId: getLoadBalancerService + summary: Get Load Balancer Service + description: Requires the `environments-view` capability. + tags: + - Services/Load Balancer + parameters: + - name: environmentId + description: The environmentId where the load balancer resides. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a load balancer info resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/LoadBalancerInfo' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/lb/tasks: + post: + operationId: createLoadBalancerServiceJob + summary: Create Load Balancer Service Job + description: Creates a task that will update the load balancer's configuration. + tags: + - Services/Load Balancer + parameters: + - name: environmentId + description: The ID of the environment where this load balancer resides. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for reconfiguring a load balancer. + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - reconfigure + description: The name of the action to perform. + contents: + type: object + properties: + high_availability: + type: + - boolean + - 'null' + description: A boolean where `true` represents the desire to run the environment load balancer service in high availability mode. + auto_update: + type: + - boolean + - 'null' + description: A boolean representing if this service container is set to autoupdate or not + config: + anyOf: + - $ref: '#/components/schemas/LoadBalancerConfig' + - type: 'null' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/lb/telemetry/report: + get: + operationId: getLoadBalancerTelemetryReport + summary: Get Load Balancer Telemetry Report + description: | + Fetches a telemetry report for Cycle's native load balancer for the specified range. + + ## Permissions + Requires the `environments-view` capability. Also requires the user to have access specifically to the requested Environment. + tags: + - Services/Load Balancer + parameters: + - name: environmentId + description: The environmentId where the load balancer resides. + in: path + required: true + schema: + type: string + - name: filter + in: query + style: deepObject + required: true + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + required: + - controller + properties: + range-start: + description: The start date from when to pull load balancer telemetry data + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull load balancer telemetry data + $ref: '#/components/schemas/DateTime' + controller: + description: The specific controller to fetch telemetry for + $ref: '#/components/schemas/DateTime' + responses: + '200': + description: Returns the load balancer telemetry report + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/LoadBalancerTelemetryReport' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/lb/telemetry/latest: + get: + operationId: getLoadBalancerLatestTelemetryReport + summary: Get Latest Load Balancer Telemetry Report. + description: | + Fetches the latest telemetry report for Cycle's native load balancer. Provides detailed information on a per-instance basis. + + ## Permissions + Requires the `environments-view` capability. Also requires the user to have access specifically to the requested Environment. + tags: + - Services/Load Balancer + parameters: + - name: environmentId + description: The environmentId where the load balancer resides. + in: path + required: true + schema: + type: string + - name: filter + in: query + style: deepObject + required: true + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + ### Required Filter + On this endpoint, you MUST pass filter[controller]. + schema: + type: object + properties: + controller: + type: string + description: | + `filter[controller]=port-123` filter for a specific controller to load telemetry for. THIS FILTER IS REQUIRED. + responses: + '200': + description: Returns the latest load balancer telemetry + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/LoadBalancerLatestTelemetry' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/lb/telemetry/latest-controllers: + get: + operationId: getLoadBalancerTelemetryLatestControllers + summary: Get Latest Load Balancer Controller Telemetry + description: | + Gets the controller information for the specified load balancer. Returns a similar struct to the 'latest' load balancer telemetry call, but does NOT return snapshots, just the controller information. + + ## Permissions + Requires the `environments-view` capability. Also requires the user to have access specifically to the requested Environment. + tags: + - Services/Load Balancer + parameters: + - name: environmentId + description: The ID of the environment of the desired load balancer. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - instances + - servers + - containers + responses: + '200': + description: Returns information about the latest controllers that produced telemetry. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/LoadBalancerLatestControllers' + includes: + $ref: '#/components/schemas/controllers' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/scheduler/tasks: + post: + operationId: createSchedulerServiceJob + summary: Create Scheduler Service Job + description: Creates a task that will update the scheduler service's configuration. + tags: + - Services/Scheduler + parameters: + - name: environmentId + description: The ID of the environment where this scheduler service resides. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for reconfiguring a scheduler service. + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + enum: + - reconfigure + description: The name of the action to perform. + contents: + type: object + properties: + config: + anyOf: + - $ref: '#/components/schemas/SchedulerConfig' + - type: 'null' + auto_update: + type: + - boolean + - 'null' + description: A boolean where `true` represents the desire to automatically update the environment scheduler service. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/vpn: + get: + operationId: getVPNService + summary: Get VPN Service + description: Requires the `environments-vpn` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The environmentId where the VPN resides. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns the VPN service. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VPNInfoReturn' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/vpn/logins: + get: + operationId: getVPNLogins + summary: Get VPN Logins + description: Requires the `environments-vpn` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The environmentId where the VPN resides. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a VPNInfo resource. + content: + application/json: + schema: + title: VPNInfoEnvironmentService + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/VPNLogin' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/vpn/users: + get: + operationId: getVPNUsers + summary: List VPN Users + description: Requires the `environments-vpn-manage` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The environmentId where the VPN service resides. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a list of VPN users for the given VPN. + content: + application/json: + schema: + title: getVPNUsersReturn + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/VPNUsers' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createVPNUser + summary: Create VPN User + description: Requires the `environments-vpn-manage` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The environmentId where the VPN service resides. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new VPN user. + content: + application/json: + schema: + type: object + required: + - username + - password + properties: + username: + type: string + password: + type: string + responses: + '201': + description: Returns a VPN User. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VPNUsers' + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/vpn/users/{userId}: + delete: + operationId: deleteVPNUser + summary: Delete VPN User + description: Requires the `environments-vpn-manage` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The environmentId where the VPN service the given user belongs to resides. + in: path + required: true + schema: + type: string + - name: userId + description: The userId of the user to be deleted. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns no data. + content: + application/json: + schema: + title: VPNUserDeleteReturn + type: object + required: + - data + properties: + data: + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/environments/{environmentId}/services/vpn/tasks: + post: + operationId: createVPNServiceJob + summary: Create VPN Service Job + description: Used to reconfigure or reset the Environment VPN. Requires the `environments-vpn-manage` capability. + tags: + - Services/VPN + parameters: + - name: environmentId + description: The ID of the Environment the VPN service resides in. + in: path + required: true + schema: + type: string + requestBody: + description: The task contents used to build the Environment VPN Job. + content: + application/json: + schema: + $ref: '#/components/schemas/VpnTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs: + get: + operationId: getHubs + summary: List Hubs + description: Lists all associated Hubs. + tags: + - Hubs + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/PageParam' + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those environments matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search hubs for a value associated with a field on the given Hub(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the Hub's current state. + responses: + '200': + description: Returns a list of Hubs. + content: + application/json: + schema: + title: ListHubsResponse + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Hub' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createHub + summary: Create Hub + description: Create a Hub. + tags: + - Hubs + security: + - bearerAuth: [] + parameters: [] + requestBody: + description: Parameters for creating a Hub. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name for the Hub. + identifier: + $ref: '#/components/schemas/Identifier' + webhooks: + $ref: '#/components/schemas/HubWebhooks' + responses: + '200': + description: Returns a Hub resource. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Hub' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current: + get: + operationId: getHub + summary: Get Hub + description: Requires the `hubs-view` capability. + tags: + - Hubs + security: + - bearerAuth: [] + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - memberships + responses: + '200': + description: Returns an hub resource. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/Hub' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateHub + summary: Update Hub + description: Updates the specified hub, setting the values of the parameters passed. + tags: + - Hubs + parameters: [] + requestBody: + description: Parameters for updating a hub. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name for the hub. + webhooks: + $ref: '#/components/schemas/HubWebhooks' + security: + $ref: '#/components/schemas/HubSecurity' + identifier: + type: string + billing_emails: + type: array + description: Email addresses that will receive any invoices or billing related correspondence. + items: + type: string + billing_contact: + oneOf: + - type: object + properties: + name: + type: + - string + - 'null' + legal_business_name: + type: + - string + - 'null' + tax_id: + type: + - string + - 'null' + - type: 'null' + responses: + '200': + description: Returns the updated Hub resource. + content: + application/json: + schema: + title: HubUpdateResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Hub' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteHub + tags: + - Hubs + security: + - bearerAuth: [] + parameters: [] + requestBody: + description: Parameters for deleting a Server. + content: + application/json: + schema: + type: object + properties: + options: + type: object + properties: + force: + description: If force is set to true, this will force delete the hub, even if there are servers running on it. + type: boolean + summary: Delete Hub + description: Requires the `hubs-delete` capability. This can only be aquired by being the hub owner. + responses: + '202': + description: Returns a task descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/capabilities: + get: + operationId: getHubCapabilities + summary: List Hub Capabilities + tags: + - Hubs + parameters: [] + security: [] + responses: + '200': + description: Returns a list of capabilities. + content: + application/json: + schema: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + $ref: '#/components/schemas/Capability' + meta: + type: object + required: + - captions + properties: + captions: + type: object + description: Human-readable captions keyed by the platform level capability it describes. + additionalProperties: + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/usage: + get: + operationId: getHubUsage + summary: Get Hub Usage + description: Requires the `hubs-view` capability. + tags: + - Hubs + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/FilterParam' + responses: + '200': + description: Returns usage detail points of the Hub over a range of time. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/HubUsageDatum' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/activity: + get: + operationId: getHubActivity + summary: List Hub Activity + tags: + - Hubs + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - users + - components + - creators + - images + - stack_builds + - stacks + - environments + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + search: + type: string + description: | + `filter[search]=value` search activities for a value associated with a field on the given activity(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the activity's current state. + user: + type: string + description: | + `filter[user]=ID` user filtering by ID. Submit the ID of the user you wish to filter for and the return will be any activity from that user. + environment: + type: string + description: | + `filter[environment]=ID` environment filtering by ID. Submit the ID of the environment you wish to filter for and the return will be any activity from that environment. + container: + type: string + description: | + `filter[container]=ID` container filtering by ID. Submit the ID of the container you wish to filter for and the return will be any activity from that container. + virtual-machine: + type: string + description: | + `filter[virtual-machine]=ID` virtual machine filtering by ID. Submit the ID of the virtual machine you wish to filter for and the return will be any activity from that virtual machine. + instance: + type: string + description: | + `filter[instance]=ID` instance filtering by ID. Submit the ID of the instance you wish to filter for and the return will be any activity from that instance. + server: + type: string + description: | + `filter[server]=ID` server filtering by ID. Submit the ID of the server you wish to filter for and the return will be any activity from that server. + events: + type: string + description: | + `filter[events]=value` filter by event names. + examples: + - filter[events]=environment.services.vpn.login + verbosity: + type: integer + description: | + `filter[verbosity]=integer` filter the activity return by verbosity. The verbosity can be: + `0` - Activity that users would find useful. + `1` - Activity that can be useful when tracking down how something happened. + `2` - Full activity, can be useful in debugging problems. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Hub Activity entries. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Activity' + includes: + $ref: '#/components/schemas/ActivityIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/api-keys: + get: + operationId: getApiKeys + summary: List API Keys + description: Requires the `api-keys-manage` capability. + tags: + - API Keys + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a collection of API Key resources. + content: + application/json: + schema: + title: ListApiKeysResponse + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ApiKey' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createApiKey + summary: Create API Key + description: Requires the `api-keys-manage` capability. + tags: + - API Keys + parameters: [] + requestBody: + description: Parameters for creating an API Key. + content: + application/json: + schema: + type: object + required: + - name + - role_id + properties: + name: + type: string + description: A name given to the API Key. + role_id: + $ref: '#/components/schemas/ID' + description: The ID of the role this API Key is a member of. + ips: + type: + - array + - 'null' + description: An array of approved IPs from which this API Key can be used. + items: + type: string + responses: + '201': + description: Returns an API Key. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ApiKey' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/api-keys/{apikeyId}: + get: + operationId: getAPIKey + summary: Get API Key + description: Requries the `api-keys-manage` capability. + tags: + - API Keys + parameters: + - name: apikeyId + description: The ID of the API Key. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - roles + responses: + '200': + description: Returns an API Key resource. + content: + application/json: + schema: + type: object + properties: + data: + $ref: '#/components/schemas/ApiKey' + includes: + $ref: '#/components/schemas/ApiKeyIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateAPIKey + summary: Update API Key + description: Requires the `api-keys-manage` capability. + tags: + - API Keys + parameters: + - name: apikeyId + description: The ID of the API Key. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating an API Key. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name given to the API Key. + role_id: + $ref: '#/components/schemas/ID' + description: The ID of the role this API Key is a member of. + ips: + type: + - array + - 'null' + description: An array of approved IPs from which this API Key can be used. + items: + type: string + responses: + '200': + description: Returns an API Key. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ApiKey' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteAPIKey + summary: Delete API Key + description: Requires the 'api-keys-manage' capability. + tags: + - API Keys + parameters: + - name: apikeyId + description: The ID of the API Key. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns an API Key. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ApiKey' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/integrations/{integrationId}: + get: + operationId: getIntegration + summary: Get Integration + description: | + Retrieves details of a single integration associated with the current hub. + + Requires the `hubs-integrations-view` capability. + tags: + - Integrations + security: + - bearerAuth: [] + parameters: + - name: integrationId + in: path + required: true + schema: + type: string + pattern: ^[a-f0-9]{24}$ + description: The ID of the integration to retrieve. + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - definition + responses: + '200': + description: Details of the specified integration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Integration' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateIntegration + tags: + - Integrations + security: + - bearerAuth: [] + summary: Update Integration + description: Updates the specified integration within the current hub. If the integration definition specifies that it requires verification, then you must submit a verify task to enable it. + parameters: + - name: integrationId + in: path + required: true + schema: + type: string + pattern: ^[a-f0-9]{24}$ + description: The ID of the integration to update. + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - definition + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: + - string + - 'null' + description: A new name for the integration. + minLength: 5 + identifier: + $ref: '#/components/schemas/Identifier' + description: The identifier of the integration. Must be unique for every integration. + minLength: 3 + auth: + anyOf: + - $ref: '#/components/schemas/IntegrationAuth' + - type: 'null' + extra: + description: Updated key-value pairs associated with the integration. + oneOf: + - type: object + additionalProperties: + type: string + - type: 'null' + responses: + '200': + description: Returns the updated integration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Integration' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteIntegration + tags: + - Integrations + security: + - bearerAuth: [] + summary: Delete an Integration + description: Deletes the specified integration from the current hub, marking it as deleted and returning the updated integration. + parameters: + - name: integrationId + in: path + required: true + schema: + type: string + pattern: ^[a-f0-9]{24}$ + description: The ID of the integration to delete. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/integrations: + get: + operationId: getIntegrations + summary: List Integrations + description: | + Lists all integrations associated with the current Hub, with optional filtering. + + Requires the `hubs-integrations-view` capability. + tags: + - Integrations + security: + - bearerAuth: [] + parameters: + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/SortParam' + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - definition + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. Supports filtering by state and a text search. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value` Filters integrations by their current state. For example, `filter[state]=active` would return only integrations in an active state. + search: + type: string + description: | + `filter[search]=value` Performs a text search across relevant fields of the integrations. For example, `filter[search]=example` would return integrations that have "example" in any of the searchable fields + category: + type: string + description: | + `filter[category]=value` Filters integrations by their category. For example, `filter[category]=infrastructure-provider` would return only integrations that are capable of provisioning infrastructure. + responses: + '200': + description: A list of integrations + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Integration' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createIntegration + summary: Create Integration + description: Create an integration resource within a hub. If the integration definition specifies that it requires verification, then you must submit a verify task to enable it. + tags: + - Integrations + security: + - bearerAuth: [] + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - definition + requestBody: + description: Parameters for creating an integration. + required: true + content: + application/json: + schema: + type: object + required: + - name + - identifier + - vendor + properties: + name: + type: string + description: A name for the integration. + minLength: 5 + vendor: + type: string + description: Unique vendor for the integration, subject to validation. + identifier: + $ref: '#/components/schemas/Identifier' + description: The identifier of the integration. Must be unique for every integration. + minLength: 3 + auth: + type: object + properties: + region: + type: + - string + - 'null' + description: The region associated with the integration. + namespace: + type: + - string + - 'null' + description: The namespace associated with the integration. + api_key: + type: + - string + - 'null' + description: API key for accessing the integration. + key_id: + type: + - string + - 'null' + description: Key ID for accessing the integration. + secret: + type: + - string + - 'null' + description: Secret for accessing the integration. + subscription_id: + type: + - string + - 'null' + description: Subscription ID for the integration. + client_id: + type: + - string + - 'null' + description: Client ID for the integration. + base64_config: + type: + - string + - 'null' + description: Base64 encoded configuration for the integration. + description: Authentication information for the integration. + extra: + type: object + additionalProperties: + type: string + description: Additional key-value pairs associated with the integration. + responses: + '201': + description: Returns the new integration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Integration' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/integrations/available: + get: + operationId: getAvailableIntegrations + summary: Get Available Integrations + description: Returns a map of available integrations categorized by their type. + tags: + - Integrations + responses: + '200': + description: A map of categories to lists of integration definitions. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + properties: + image-builders: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/IntegrationDefinition' + object-storage: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/IntegrationDefinition' + tls-certificate-generation: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/IntegrationDefinition' + infrastructure-provider: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/IntegrationDefinition' + billing: + type: + - array + - 'null' + items: + $ref: '#/components/schemas/IntegrationDefinition' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/integrations/{integrationId}/tasks: + post: + operationId: createIntegrationJob + description: | + Creates a new Job targeted at the provided Hub Integration. + + ## Required Permissions + - Requires a valid hub membership to the target hub. + - Requires the `hubs-integrations-manage` capability. + tags: + - Integrations + parameters: + - name: integrationId + description: The ID of the Hub Integration. + in: path + required: true + schema: + type: string + summary: Create a new Hub Integration Job. + requestBody: + description: Parameters for creating a new Hub Integration Job. + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + description: The type of Job/selected Job action to create. + enum: + - verify + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/members: + get: + operationId: getHubMembers + summary: List Hub Members + description: Requires the `hubs-members-view` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - accounts + - roles + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Hub Memberships. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubMembershipIncludes-2' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/membership: + get: + operationId: getHubMembership + summary: Get Hub Membership + description: Gets the Hub Membership for the requesting Account. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - accounts + - roles + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubMembershipIncludes-2' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/members/{memberId}: + get: + operationId: getHubMember + summary: Get Hub Member + description: Requires the `hubs-members-view` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: memberId + description: The ID for the given Hub member. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - accounts + - roles + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubMembershipIncludes-2' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateHubMember + summary: Update Hub Member + description: Requires the `hubs-members-manage` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: memberId + description: The ID for the given member. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a Hub membership. + content: + application/json: + schema: + type: object + properties: + role_id: + description: The account role. + $ref: '#/components/schemas/ID' + permissions: + $ref: '#/components/schemas/Permissions' + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteHubMember + summary: Delete Hub Member + description: Requires the `hubs-members-manage` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: memberId + description: The ID of the given Hub Member. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/members/account/{accountId}: + get: + operationId: getHubMemberAccount + summary: Get Hub Member Account + description: Requires the `hubs-members-view` capability. + tags: + - Members + parameters: + - name: accountId + description: The ID of the member's Account. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - capabilities + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - accounts + - roles + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubMembershipIncludes-2' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/invites: + get: + operationId: getHubInvites + summary: List Hub Invites + description: Requires the `hubs-invites-manage` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - capabilities + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - senders + - roles + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Memberships. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/HubMembership' + includes: + $ref: '#/components/schemas/HubInviteIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createHubInvite + summary: Create Hub Invite + description: Requires the `hubs-invites-send` capability. + tags: + - Members + parameters: [] + requestBody: + description: Parameters for creating a Hub invite. + content: + application/json: + schema: + type: object + properties: + recipient: + type: string + description: The email address of the invitee. + role_id: + description: The account role. + $ref: '#/components/schemas/ID' + permissions: + type: object + description: The Environment permissions the invitee will have + required: + - all_environments + - environments + properties: + all_environments: + type: boolean + description: Boolean value that indicates the user has access to all Environments + environments: + type: array + description: A list of objects that describe the specific environments the invitee will have access to + items: + type: object + required: + - id + - manage + properties: + id: + type: string + description: The ID of the Environment + manage: + type: boolean + description: Boolean indicating the invitee has manage rights to Environment + responses: + '201': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/invites/{inviteId}: + delete: + operationId: deleteHubInvite + summary: Delete Hub Invite + description: Requires the `hub-invites-manage` capability. + tags: + - Members + security: + - bearerAuth: [] + parameters: + - name: inviteId + description: The ID of the Hub Invite. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a Hub Membership. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/HubMembership' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/notifications: + get: + operationId: getHubNotificationSocketAuth + summary: Hub Notification Pipeline Auth + description: | + Initializes authorization for the Hub notification pipeline. The Hub notification pipeline is a one-way streaming websocket that + sends real-time 'notifications' as things are happening on the Hub. These notifications tell some basic information about an event, + and it is up to the user to fetch additional details, if deemed necessary. + + Requesting this endpoint without a `?token=` URL parameter will result in receiving a short lived token in the response body. That + token can then be applied to the URL parameter to the same endpoint to upgrade the connection to a WebSocket. + + Requires the `apionly-notifications-listen` capability. + tags: + - Hub Notifications + parameters: [] + responses: + '101': + description: WebSocket protocol upgrade response, connection is upgraded to WebSocket. + headers: + Connection: + description: Should be 'upgrade'. + schema: + type: string + Upgrade: + description: Specifies the protocol to which the connection is upgraded. + schema: + type: string + enum: + - websocket + Sec-WebSocket-Accept: + description: Accept key for the WebSocket protocol handshake. + schema: + type: string + x-websocket: + description: Indicates that this operation is expected to initiate a WebSocket connection. + url: ws://example.com/ws + '200': + description: Returns the credentials necessary for upgrading this connection into a web socket. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + title: HubNotificationPipelineAuthResponse + type: object + required: + - token + properties: + token: + type: string + description: A token used for connecting to the Hub notification pipeline websocket API. + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/roles: + get: + operationId: getRoles + summary: List Hub Roles + description: | + Lists the Roles that have been created for this Hub. + + Requires the `hubs-roles-manage` capability. + tags: + - Roles + parameters: + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/FilterParam' + - $ref: '#/components/parameters/PageParam' + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - counts + responses: + '200': + description: Returns a list of Hub Roles. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Role' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createRole + tags: + - Roles + parameters: [] + summary: Create Hub Role + description: | + Creates a custom Role for a Hub. + + Requires the `hubs-roles-manage` capability. + requestBody: + description: Parameters for creating a new Hub Role. + content: + application/json: + schema: + type: object + required: + - identifier + - rank + properties: + name: + type: + - string + - 'null' + description: A name given to the Role. + identifier: + type: string + capabilities: + description: The list of platform level capabilities assigned to this Role. + oneOf: + - type: object + required: + - all + - specific + properties: + all: + type: boolean + specific: + type: array + items: + $ref: '#/components/schemas/Capability' + - type: 'null' + rank: + type: integer + description: An integer between 0 and 10 that indicates the Role hierarchy. An account can only edit a Role that is less than their rank. The 'owner' Role is rank 10. + extra: + description: Custom user-defined properties for storing extra information on the Role. Not utilized by Cycle. + oneOf: + - type: object + additionalProperties: + type: string + - type: 'null' + responses: + '201': + description: Returns a Hub Role. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Role' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/roles/{roleId}: + get: + operationId: getRole + summary: Get Hub Role + description: | + Retrieves the specified Role. + + Requries the `hubs-roles-manage` capability. + tags: + - Roles + parameters: + - name: roleId + description: The ID of the Role. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - counts + responses: + '200': + description: Returns a Role. + content: + application/json: + schema: + title: GetRoleResponse + type: object + properties: + data: + $ref: '#/components/schemas/Role' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateRole + summary: Update Hub Role + description: | + Updates various properties of a specific Role. + + Requires the `hubs-roles-manage` capability. + tags: + - Roles + parameters: + - name: roleId + description: The ID of the Role. + in: path + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - identifier + - rank + properties: + name: + type: + - string + - 'null' + description: A name given to the Role. + identifier: + type: string + capabilities: + description: The list of platform level capabilities assigned to this Role. + oneOf: + - type: object + required: + - all + - specific + properties: + all: + type: boolean + description: If true, the Role has all capabilities. + specific: + type: array + items: + $ref: '#/components/schemas/Capability' + - type: 'null' + rank: + type: integer + extra: + description: Custom user-defined properties for storing extra information on the Role. Not utilized by Cycle. + oneOf: + - type: object + additionalProperties: + type: string + - type: 'null' + responses: + '200': + description: Returns the updated Hub Role. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Role' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteRole + summary: Delete Hub Role + description: | + Marks a Role as 'deleted'. + + Requires the 'hubs-roles-manage' capability. + tags: + - Roles + parameters: + - name: roleId + description: The ID of the Role. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/hubs/current/roles/defaults: + get: + operationId: getDefaultHubRoles + summary: List Default Hub Roles + tags: + - Roles + parameters: [] + security: [] + responses: + '200': + description: Returns a list of the default roles/capabilities for a hub. + content: + application/json: + schema: + type: object + required: + - data + - meta + properties: + data: + type: array + items: + type: object + title: DefaultRole + required: + - name + - identifier + - root + - capabilities + properties: + name: + type: string + identifier: + $ref: '#/components/schemas/Identifier' + root: + description: The role marked as root has full moderation control over all roles. + type: boolean + capabilities: + type: object + required: + - all + - specific + properties: + all: + type: boolean + description: If true, the role has all capabilities. + specific: + type: array + items: + $ref: '#/components/schemas/Capability' + default: + $ref: '#/components/responses/DefaultError' + /v1/images: + get: + operationId: getImages + summary: List Images + description: Requires the `images-view` capability. + tags: + - Images + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - stack_builds + - stacks + - sources + - integrations + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those images matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given Image(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the Image's current state. + source_type: + type: string + description: | + `filter[source_type]=value` filter images by the Image source's type. Can be: `direct`, `stack-build`, or `bucket` + source_id: + type: string + description: | + `filter[source_id]=ID` Image filtering by source ID. Submit the ID of the Image source you wish to filter for and the return will be any Images created from that source. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Images. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Image' + includes: + $ref: '#/components/schemas/ImageIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createImage + summary: Create Image + description: Requires the `images-manage` capability. + tags: + - Images + parameters: [] + requestBody: + description: Parameters for creating a new Image. + content: + application/json: + schema: + type: object + required: + - source_id + properties: + name: + type: string + description: A name for the Image. + source_id: + type: string + description: The ID for the Image source to be used. + build: + type: object + description: A build object, holding information important to the Image build. + properties: + args: + type: object + description: An object holding key value build time arguments needed for the Image during build time. + additionalProperties: + type: string + use_disk: + type: boolean + description: If true, will skip using /dev/shm when building an image on factory. Allows for building much larger images. + override: + type: object + description: An override object to be used for a single Image create request. + properties: + target: + type: string + description: For Image sources with `docker-hub` or `docker-registry` origin types. A target to be used for overridding the default target - should include an Image and a tag. + targz_url: + type: string + description: For Image sources with `docker-file` origin types. A URL pointing to a .tar.gz file of a repo with a Dockerfile in it - can be used instead of linking Cycle directly to a repository. + responses: + '201': + description: Returns an Image. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Image' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/{imageId}: + get: + operationId: getImage + summary: Get Image + description: Requires the `images-view` capability. + tags: + - Images + parameters: + - name: imageId + in: path + required: true + description: The ID of the image. + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - stack_builds + - stacks + - sources + - integrations + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a Image. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Image' + includes: + $ref: '#/components/schemas/ImageIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateImage + summary: Update Image + description: Requires the `images-manage` capability. + tags: + - Images + parameters: + - name: imageId + in: path + required: true + description: The ID of the image. + schema: + type: string + requestBody: + description: Parameters for creating a new image. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name for the image. + responses: + '200': + description: Returns an Image. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Image' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteImage + summary: Delete Image + description: Requires the `images-manage` capability. + tags: + - Images + parameters: + - name: imageId + in: path + required: true + description: The ID of the image. + schema: + type: string + responses: + '200': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/{imageId}/build-log: + get: + operationId: getImageBuildLog + summary: Get Image Build Log + description: Requires the `images-view` capability. + tags: + - Images + parameters: + - name: imageId + in: path + required: true + description: The ID of the Image. + schema: + type: string + responses: + '200': + description: Returns an Image's build log. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/BuildLog' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/tasks: + post: + operationId: createImagesJob + summary: Prune Images + description: | + Used to perform different actions on a given image. + + Requires the `images-manage` capability. + tags: + - Images + parameters: [] + requestBody: + description: Parameters for creating a new Images Job. + content: + application/json: + schema: + type: object + required: + - action + - contents + properties: + action: + type: string + description: The action is the Job type to create. + enum: + - prune + contents: + type: object + description: Additional contents needed by the platform to create the job. + required: + - source_ids + properties: + source_ids: + description: A list of IDs to be pruned. + type: array + items: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/{imageId}/tasks: + post: + operationId: createImageJob + summary: Create Image Job + description: | + Used to perform different actions on a given Image. + + Requires the `images-import` capability. + tags: + - Images + parameters: + - name: imageId + description: The ID of the requested Image. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new Image job. + content: + application/json: + schema: + type: object + required: + - action + properties: + action: + type: string + enum: + - import + responses: + '200': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/sources: + get: + operationId: getImageSources + summary: List Image Sources + description: Requires the `images-sources-view` capability. + tags: + - Image Sources + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - images_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - integrations + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + identifier: + type: string + description: | + `filter[identifier]=value` List only those image sources matching this identifier. May return multiple results. + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given Image Source(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the Image Source's current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Image Sources. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ImageSource' + includes: + $ref: '#/components/schemas/SourceIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createImageSource + summary: Create Image Source + description: Requires the `images-sources-manage` capability. + tags: + - Image Sources + parameters: [] + requestBody: + description: Parameters for creating an Image Source. + content: + application/json: + schema: + type: object + required: + - type + - origin + properties: + name: + type: string + description: A name for the Image Source. + identifier: + $ref: '#/components/schemas/Identifier' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + builder: + oneOf: + - type: object + required: + - integration_id + properties: + integration_id: + $ref: '#/components/schemas/HybridIdentifier' + - type: 'null' + type: + $ref: '#/components/schemas/ImageSourceType' + origin: + $ref: '#/components/schemas/ImageOrigin' + about: + type: object + description: User defined information about the Image Source. + required: + - description + properties: + description: + type: + - string + - 'null' + description: A description of the Image Source. + responses: + '201': + description: Returns an Image Source. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ImageSource' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/sources/{sourceId}: + get: + operationId: getImageSource + summary: Get Image Source + description: Requires the `images-sources-view` capability. + tags: + - Image Sources + parameters: + - name: sourceId + in: path + required: true + description: The ID of the Image Source. + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - images_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - integrations + responses: + '200': + description: Returns an Image Source. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ImageSource' + includes: + $ref: '#/components/schemas/SourceIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateImageSource + summary: Update Image Source + description: Requires the `images-sources-manage` capability. + tags: + - Image Sources + parameters: + - name: sourceId + in: path + required: true + description: The ID of the Image Source. + schema: + type: string + requestBody: + description: Parameters for updating an image source. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: A name for the image source. + identifier: + anyOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + origin: + $ref: '#/components/schemas/ImageOrigin' + builder: + oneOf: + - type: object + properties: + integration_id: + anyOf: + - $ref: '#/components/schemas/HybridIdentifier' + - type: 'null' + - type: 'null' + about: + type: object + description: User defined information about the image source. + required: + - description + properties: + description: + type: + - string + - 'null' + description: A description of the image source. + responses: + '200': + description: Returns an Image Source. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ImageSource' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteImageSource + summary: Delete Image Source + description: Requires the `images-sources-manage` capability. + tags: + - Image Sources + parameters: + - name: sourceId + in: path + required: true + description: The ID of the Image Source. + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/images/sources/{sourceId}/access: + patch: + operationId: updateImageSourceAccess + summary: Update Image Source Access + description: Requires the `images-sources-manage` capability. If an ACL is present, requires the `manage` privilege. + tags: + - Image Sources + parameters: + - name: sourceId + in: path + required: true + description: The ID of the Image Source. + schema: + type: string + requestBody: + description: Parameters for updating an image source. + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns an Image Source. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ImageSource' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/summary: + get: + operationId: getInfrastructureSummary + summary: Get Infrastructure Summary + description: Requires the `infrastructure-servers-view` capability. + tags: + - Infrastructure + parameters: + - name: filter + in: query + required: false + style: deepObject + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + cluster: + type: string + description: | + `filter[cluster]=value` return an infrastructure summary only for the specified cluster. + responses: + '200': + description: Returns an infrastructure summary. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/InfrastructureSummary' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/deployment-strategies: + get: + operationId: getDeploymentStrategies + summary: Get Deployment Strategies + description: Gets the available deployment strategies that can be used to orchestrate containers. + tags: + - Infrastructure + parameters: [] + responses: + '200': + description: Returns available deployment strategies. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + properties: + resource-density: + $ref: '#/components/schemas/DeploymentStrategy' + high-availability: + $ref: '#/components/schemas/DeploymentStrategy' + distributed: + $ref: '#/components/schemas/DeploymentStrategy' + first-available: + $ref: '#/components/schemas/DeploymentStrategy' + node: + $ref: '#/components/schemas/DeploymentStrategy' + edge: + $ref: '#/components/schemas/DeploymentStrategy' + manual: + $ref: '#/components/schemas/DeploymentStrategy' + function: + $ref: '#/components/schemas/DeploymentStrategy' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/monitoring-tiers: + get: + operationId: getClusterMonitoringTiers + summary: Get Cluster Monitoring Tiers + description: | + Gets all the available monitoring tiers that can be enabled for a cluster. + tags: + - Clusters + responses: + '200': + description: A list of monitoring tiers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + additionalProperties: + $ref: '#/components/schemas/MonitoringTierDetails' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes: + get: + operationId: getExternalVolumes + summary: List External Volumes + description: Requires the `external-volumes-view` capability. + tags: + - External Volumes + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - name: include + in: query + required: false + description: | + A comma-separated list of include values. Included resources will show up under the root document's `include` field. + In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - locations + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + location: + type: string + description: | + `filter[location]=value` List only those attached volumes available at the specified location. + server: + type: string + description: | + `filter[server-id]=value` List only those attached volumes attached to the specified server. + cluster: + type: string + description: | + `filter[search]=value` List only those attached volumes within the specified cluster. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the attached volume's current state. + unused: + type: string + description: | + `filter[unused]=true` List only those external volumes that are unused (not attached). + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of external volumes. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ExternalVolume' + includes: + $ref: '#/components/schemas/ExternalVolumeIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createExternalVolume + summary: Create External Volume + description: Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - name: include + in: query + required: false + description: | + A comma-separated list of include values. Included resources will show up under the root document's `include` field. + In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - locations + requestBody: + content: + application/json: + schema: + type: object + required: + - name + - cluster + - location_id + - server_ids + - attachment + - source + - options + properties: + name: + type: string + description: A custom name for the external volume. + identifier: + oneOf: + - $ref: '#/components/schemas/Identifier' + - type: 'null' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + cluster: + type: string + description: The cluster this external volume is associated with. + location_id: + $ref: '#/components/schemas/ID' + server_ids: + type: array + items: + $ref: '#/components/schemas/ID' + source: + $ref: '#/components/schemas/ExternalVolumeSource' + attachment: + description: Information about the resource the external volume is currently attached to. + $ref: '#/components/schemas/ExternalVolumeAttachment' + options: + $ref: '#/components/schemas/ExternalVolumeOptions' + about: + oneOf: + - type: object + description: Additional details about the external volume. + required: + - description + properties: + description: + type: string + description: A custom description for this external volume. + - type: 'null' + responses: + '201': + description: Returns an external volume. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ExternalVolume' + includes: + $ref: '#/components/schemas/ExternalVolumeIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes/tasks: + post: + operationId: createExternalVolumesJob + summary: Create External Volumes Job + description: | + Create a job for external volumes. + + Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: [] + requestBody: + description: Parameters for creating a new external volumes job. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalVolumesTask' + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes/{externalVolumeId}: + get: + operationId: getExternalVolume + summary: Get External Volume + description: | + Retrieves a single external volume by ID. + + Requires the `external-volumes-view` capability. + tags: + - External Volumes + parameters: + - name: externalVolumeId + description: The ID of the external volume. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: | + A comma-separated list of meta values. Meta values will show up under a resource's `meta` field. + In the case of applying a meta to a collection of resources, each resource will have its own relevant meta data. + In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - name: include + in: query + required: false + description: | + A comma-separated list of include values. Included resources will show up under the root document's `include` field. + In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - locations + responses: + '200': + description: Returns the requested virtual machine. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ExternalVolume' + includes: + $ref: '#/components/schemas/ExternalVolumeIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateExternalVolume + summary: Update External Volume + description: | + Updates the specified external volume. + + Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: + - name: externalVolumeId + description: The ID of the external volume. + in: path + required: true + schema: + type: string + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - containers + - name: include + in: query + required: false + description: | + A comma-separated list of include values. Included resources will show up under the root document's `include` field. + In the case of applying an include to a collection of resources, if multiple resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - locations + requestBody: + description: Parameters for updating the external volume. + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The new name of the external volume. + identifier: + description: The new identifier of the external volume. + $ref: '#/components/schemas/Identifier' + options: + $ref: '#/components/schemas/ExternalVolumeOptions' + about: + type: object + properties: + description: + type: string + description: Updated description for the attached volume. + responses: + '200': + description: Returns the updated external volume. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ExternalVolume' + includes: + $ref: '#/components/schemas/ExternalVolumeIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteExternalVolume + summary: Delete External Volume + description: Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: + - name: externalVolumeId + description: The ID of the external volume to delete. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for deleting a external volume. + content: + application/json: + schema: + type: object + properties: + options: + type: object + properties: + source_device: + description: If source device is set to true, this will delete the underlying source device. + type: boolean + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes/sources: + get: + operationId: getExternalVolumeSources + summary: List External Volume Sources + description: Requires the `external-volumes-view` capability. + tags: + - External Volumes + responses: + '200': + description: Returns supported external volume sources and their capabilities. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + additionalProperties: + type: object + title: ExternalVolumeSource + required: + - capabilities + - creatable + properties: + capabilities: + type: object + description: Map where keys are attachment types and values are arrays of supported modes. + additionalProperties: + type: array + items: + type: string + creatable: + type: boolean + description: Whether volumes of this source type can be created via the API. + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes/{externalVolumeId}/access: + patch: + operationId: updateExternalVolumeAccess + summary: Update External Volume Access + description: | + Updates the ACL of the specified external volume. + + Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: + - name: externalVolumeId + description: The ID of the external volume. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating the external volume ACL. + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns the updated external volume. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/ExternalVolume' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/external-volumes/{externalVolumeId}/tasks: + post: + operationId: createExternalVolumeJob + summary: Create External Volume Job + description: | + Create a job for an external volume. + + Requires the `external-volumes-manage` capability. + tags: + - External Volumes + parameters: + - name: externalVolumeId + description: The ID of the attached volume. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new attached volume job. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalVolumeTask' + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/auto-scale/groups: + get: + operationId: getAutoScaleGroups + summary: List Auto-Scale Groups + description: Requires the `autoscale-groups-manage` capability. + tags: + - Auto-Scale Groups + parameters: + - $ref: '#/components/parameters/PageParam' + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + - models + - locations + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + search: + type: string + description: | + `filter[search]=value` search for a value associated with a field on the given auto-scale group(s). + cluster: + type: string + description: | + `filter[cluster]=value` return a list of auto-scale groups that are associated with the specified cluster. + identifier: + type: string + description: | + `filter[identifier]=value` list only those auto-scale groups matching this identifier. May return multiple results. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the provider's current state. + responses: + '200': + description: Returns a list of Auto-Scale Groups. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/AutoScaleGroup' + includes: + $ref: '#/components/schemas/AutoScaleGroupIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createAutoScaleGroup + summary: Create Auto-Scale Group + description: Requires the 'autoscale-groups-manage' + tags: + - Auto-Scale Groups + parameters: [] + requestBody: + description: Parameters for creating an Auto-Scale Group + content: + application/json: + schema: + type: object + required: + - name + - identifier + - cluster + - scale + - infrastructure + properties: + name: + type: string + identifier: + type: string + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + cluster: + type: string + scale: + $ref: '#/components/schemas/AutoScaleGroupScale' + infrastructure: + $ref: '#/components/schemas/AutoScaleGroupInfrastructure' + responses: + '201': + description: Returns an Auto-Scale Group. + content: + application/json: + schema: + title: CreateAutoScaleGroupResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/AutoScaleGroup' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/auto-scale/groups/{groupId}: + get: + operationId: getAutoScaleGroup + summary: Get Auto-Scale Group + description: Requires the `autoscale-groups-view` capability. + tags: + - Auto-Scale Groups + parameters: + - name: groupId + description: The ID for the given Auto-Scale Group. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + - models + - locations + responses: + '200': + description: Returns an Auto-Scale Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/AutoScaleGroup' + includes: + $ref: '#/components/schemas/AutoScaleGroupIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateAutoScaleGroup + summary: Update Auto-Scale Group + description: Requires the `autoscale-groups-manage` capability. + tags: + - Auto-Scale Groups + parameters: + - name: groupId + description: The ID for the given Auto-Scale Group. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating an Auto-Scale Group + content: + application/json: + schema: + type: object + properties: + name: + type: + - string + - 'null' + identifier: + type: + - string + - 'null' + scale: + anyOf: + - $ref: '#/components/schemas/AutoScaleGroupScale' + - type: 'null' + infrastructure: + anyOf: + - $ref: '#/components/schemas/AutoScaleGroupInfrastructure' + - type: 'null' + responses: + '200': + description: Returns an Auto-Scale Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/AutoScaleGroup' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteAutoScaleGroup + summary: Delete Auto-Scale Group + description: Requires the `autoscale-group-manage` capability. + tags: + - Auto-Scale Groups + parameters: + - name: groupId + description: The ID for the given autoscale group. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a task descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/auto-scale/groups/{groupId}/access: + patch: + operationId: updateAutoScaleGroupAccess + summary: Update Auto-Scale Group Access + description: Requires the `autoscale-groups-manage` capability. If an ACL is present, requires the `manage` privilege. + tags: + - Auto-Scale Groups + parameters: + - name: groupId + description: The ID for the given Auto-Scale Group. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating an Auto-Scale Group + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns an Auto-Scale Group. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/AutoScaleGroup' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/providers/{integrationId}/servers: + get: + operationId: getProviderServerModels + summary: List Provider Server Models + tags: + - Providers + parameters: + - name: integrationId + description: | + The infrastructure provider integration ID to query for server models. + Can also use a vendor string. Example `gcp`, `equinix-metal`, `abstraction`, etc. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + location_ids: + type: string + description: | + `filter[location_ids]=value` List only those provider servers matching this location. May return multiple results. + responses: + '200': + description: A list of currently provisioned servers associated with a Provider Integration. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProviderServerModel' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/providers/{integrationId}/locations: + get: + operationId: getProviderLocations + summary: List Provider Locations + tags: + - Providers + parameters: + - name: integrationId + description: | + The infrastructure provider integration ID to query for server models. + Can also use a vendor string. Example `gcp`, `equinix-metal`, `abstraction`, etc. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: A list of locations this Provider Integration supports. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ProviderLocation' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/virtual-providers/{integrationId}/isos: + post: + operationId: createVirtualProviderIso + summary: Create Virtual Provider Iso + description: | + Create an ISO for a virtual provider. + + Requires the `servers-manage` capability. + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration to execute the job on. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new virtual provider job. + content: + application/json: + schema: + type: object + required: + - name + - config + properties: + name: + description: The name of the ISO. + type: string + config: + type: object + required: + - token + properties: + token: + type: string + description: Authentication token for the ISO. + ipxe: + oneOf: + - $ref: '#/components/schemas/VirtualProviderIsoIpxeConfig' + - type: 'null' + server: + oneOf: + - $ref: '#/components/schemas/VirtualProviderIsoServerConfig' + - type: 'null' + responses: + '201': + description: Returns an ISO. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VirtualProviderIso' + default: + $ref: '#/components/responses/DefaultError' + get: + operationId: getVirtualProviderIsos + summary: Get ISOs for a virtual provider + description: | + Get ISOs for a virtual provider. + + Requires the `servers-manage` capability. + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the integration. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + - $ref: '#/components/parameters/PageParam' + - $ref: '#/components/parameters/SortParam' + responses: + '200': + description: Returns an a list of ISOs. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/VirtualProviderIso' + includes: + $ref: '#/components/schemas/VirtualProviderIsoIncludes' + /v1/infrastructure/virtual-providers/{integrationId}/isos/{isoId}: + delete: + operationId: deleteVirtualProviderIso + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration. + in: path + required: true + schema: + type: string + - name: isoId + description: The ID for the virtual provider ISO. + in: path + required: true + schema: + type: string + summary: Delete ISO + description: Requires the `servers-manage` capability. + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + get: + operationId: getVirtualProviderIso + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration. + in: path + required: true + schema: + type: string + - name: isoId + description: The ID for the virtual provider ISO. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - integrations + summary: Get ISO + description: Requires the `servers-manage` capability. + responses: + '202': + description: Returns a virtual provider ISO. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VirtualProviderIso' + includes: + $ref: '#/components/schemas/VirtualProviderIsoIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateVirtualProviderIso + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration. + in: path + required: true + schema: + type: string + - name: isoId + description: The ID for the virtual provider ISO. + in: path + required: true + schema: + type: string + summary: Update ISO + description: Requires the `servers-manage` capability. + requestBody: + description: Parameters for updating an ISO. + content: + application/json: + schema: + type: object + properties: + name: + description: The name of the ISO. + type: string + config: + type: object + properties: + token: + type: string + description: Authentication token for the ISO. Only available when ISO is in new state. + ipxe: + description: ISO IPXE configuration. Only available when ISO is in new state. + oneOf: + - $ref: '#/components/schemas/VirtualProviderIsoIpxeConfig' + - type: 'null' + server: + oneOf: + - $ref: '#/components/schemas/VirtualProviderIsoServerConfig' + - type: 'null' + responses: + '202': + description: Returns a virtual provider ISO. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/VirtualProviderIso' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/virtual-providers/{integrationId}/isos/{isoId}/tasks: + post: + operationId: createVirtualProviderIsoJob + summary: Create Virtual Provider Iso Job + description: | + Create a job for a virtual provider iso. + + Requires the `servers-manage` capability. + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration. + in: path + required: true + schema: + type: string + - name: isoId + description: The ID for the virtual provider ISO. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating a new virtual provider iso job. + content: + application/json: + schema: + $ref: '#/components/schemas/VirtualProviderIsoTask' + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + title: TaskResponse + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/virtual-providers/{integrationId}/isos/{isoId}/download: + get: + operationId: getVirtualProviderIsoDownloadUrl + tags: + - Virtual Providers + parameters: + - name: integrationId + description: The ID of the virtual provider integration. + in: path + required: true + schema: + type: string + - name: isoId + description: The ID for the virtual provider ISO. + in: path + required: true + schema: + type: string + summary: Delete ISO + description: Requires the `servers-manage` capability. + responses: + '202': + description: Returns a download URL. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - url + properties: + url: + type: string + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/clusters: + get: + operationId: getClusters + summary: List Clusters + description: Requires the `clusters-view` capability. + tags: + - Clusters + parameters: + - $ref: '#/components/parameters/PageParam' + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + essential: + type: string + description: | + `filter[essential]=true` filter for essential/non-essential clusters. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the cluster's current state. + `filter[stack_build]=ID` stack build filtering by ID. Submit the ID of the stack build you wish to filter for and the return sill be any environments that have the stack build deployed to them. + responses: + '200': + description: Returns a list of clusters. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Cluster' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createCluster + summary: Create Cluster + description: Requires the `clusters-manage` capability. + tags: + - Clusters + parameters: [] + requestBody: + description: Parameters for creating a new cluster. + content: + application/json: + schema: + type: object + required: + - identifier + properties: + identifier: + $ref: '#/components/schemas/Identifier' + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '201': + description: Returns a cluster. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Cluster' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/clusters/{clusterId}: + get: + operationId: getCluster + summary: Get Cluster + description: | + Gets a Cluster. + Requires the `clusters-view` capability. + tags: + - Clusters + parameters: + - name: clusterId + description: The ID or identifier of the requested cluster. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns a cluster. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Cluster' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateCluster + summary: Update Cluster + description: Requires the `clusters-manage` capability. + tags: + - Clusters + parameters: + - name: clusterId + description: The ID of the requested cluster. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a cluster. + content: + application/json: + schema: + type: object + properties: + non_essential: + type: boolean + description: | + Set to true to mark the cluster as 'non-essential'. Non-essential cluster resources are excluded by default from certain metrics and summaries unless opted in. + responses: + '200': + description: Returns a cluster. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Cluster' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteCluster + summary: Delete Cluster + description: Requires the `clusters-manage` capability. + tags: + - Clusters + parameters: + - name: clusterId + description: The ID of the requested cluster. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/clusters/{clusterId}/access: + patch: + operationId: updateClusterAccess + summary: Update Cluster Access + description: Requires the `clusters-manage` capability. If an ACL is present, requires the `manage` privilege. + tags: + - Clusters + parameters: + - name: clusterId + description: The ID of the requested cluster. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a cluster. + content: + application/json: + schema: + type: object + properties: + acl: + anyOf: + - $ref: '#/components/schemas/ACL' + - type: 'null' + responses: + '200': + description: Returns a cluster. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Cluster' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/clusters/{clusterId}/tasks: + post: + operationId: createClusterJob + summary: Create Cluster Job + description: Used to perform different actions on a given cluster. Requires the `clusters-manage` capability. + tags: + - Clusters + parameters: + - name: clusterId + description: The ID for the given cluster. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating the new cluster Job. + content: + application/json: + schema: + $ref: '#/components/schemas/ClusterTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers: + get: + operationId: getServers + summary: List Servers + description: Requires the `servers-view` capability. + tags: + - Servers + parameters: + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - node + - instances_count + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - locations + - models + - integrations + - clusters + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the provider's current state. + tags: + type: string + description: | + `filter[tags]=tagone,tagtwo,tagthree` filtering by Server tag. Enter one or more tags (comma separated) and the return will include servers that match any tags in the list. + cluster: + type: string + description: | + `filter[cluster]=clusterIdentifier` filtering by cluster. Enter the cluster identifier and the return will include servers belonging to the specified cluster. + location: + type: string + description: | + `filter[location]=location` filtering by location. Enter the location id and the return will include servers belonging to the specified location. + providers: + type: string + description: | + `filter[providers]=providerone,providertwo` filtering by provider. Enter one or more providers (commas separated) and the return will include servers that match any providers in the list. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Servers. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Server' + includes: + $ref: '#/components/schemas/ServerIncludes' + default: + $ref: '#/components/responses/DefaultError' + post: + operationId: createServers + summary: Create Servers + description: Requires the `servers-provision` capability. + tags: + - Servers + parameters: [] + requestBody: + description: Parameters for creating a Server. + content: + application/json: + schema: + type: object + required: + - servers + - cluster + properties: + cluster: + type: string + description: The existing or new cluster this infrastructure should be provisioned in. + servers: + description: An array of servers to provision. + type: array + items: + type: object + required: + - integration_id + - model_id + - location_id + - quantity + properties: + integration_id: + $ref: '#/components/schemas/ID' + description: The ID of the provider integration to use for this Server. + model_id: + type: string + description: The model ID of the Server. + location_id: + type: string + description: The location ID of the Server. + advanced: + oneOf: + - type: object + properties: + provision_options: + oneOf: + - type: object + description: Advanced options to apply to the provisioning of a server. + properties: + attached_storage_size: + oneOf: + - type: integer + - type: 'null' + description: | + For providers that support setting this value dynamically; + A number representing the GB size of the volume to be attached to the server. + reservation_id: + oneOf: + - type: string + - type: 'null' + description: | + A reservation ID to be used to provision a server that has been reserved at the provider. + encrypt_storage: + oneOf: + - type: boolean + - type: 'null' + description: | + For providers that support this setting, this option will encrypt storage for server. + - type: 'null' + zone: + oneOf: + - type: string + - type: 'null' + - type: 'null' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}: + get: + operationId: getServer + summary: Get Server + description: Requires the `servers-view` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID for the given Server. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - locations + - models + - integrations + - clusters + - name: meta + in: query + required: false + description: A comma separated list of meta values. Meta values will show up under a resource's `meta` field. In the case of applying a meta to a collection of resources, each resource will have it's own relevant meta data. In some rare cases, meta may not apply to individual resources, and may appear in the root document. These will be clearly labeled. + schema: + type: array + items: + type: string + enum: + - node + - instances_count + - allocations + responses: + '200': + description: Returns a Server. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Server' + includes: + $ref: '#/components/schemas/ServerIncludes' + default: + $ref: '#/components/responses/DefaultError' + patch: + operationId: updateServer + summary: Update Server + description: Requires the `servers-manage` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID for the given Server. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for updating a Server. + content: + application/json: + schema: + type: object + required: + - constraints + properties: + nickname: + description: A custom name given to the server for identification purposes. Does not affect server hostname. + type: + - string + - 'null' + constraints: + type: object + description: Server constriants. + properties: + tags: + description: A list of Server tags. + type: array + items: + type: string + allow: + type: object + description: Server constraints for the given Server. + required: + - pool + - services + - overcommit + properties: + pool: + type: boolean + description: A boolean where true represents the Server can accept containers with no tags set. + services: + type: boolean + description: A boolean where true represents the Server being a target for service containers. + overcommit: + type: boolean + description: A boolean where true represents the desire for the Server to allow the overcommitting of shares. + overcommit_multiple: + type: + - integer + - 'null' + description: An integer that describes the capability of a server to overcommit shares. This will allow more containers to run on a given server based on the servers available CPU. 1 thread (or vCPU) = 10 shares. + responses: + '200': + description: Returns a Server. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Server' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteServer + summary: Delete Server + description: Requires the `servers-manage` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID of the Server. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for deleting a Server. + content: + application/json: + schema: + type: object + properties: + options: + type: object + properties: + force: + description: If force is set to true, this will force delete the server, even if there are instances running on it. + type: boolean + responses: + '200': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}/telemetry: + get: + operationId: getServerTelemetry + summary: Get Server Telemetry + description: | + This call requires the filter query parameter to be used. + + Requires the `servers-view` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID for the given Server. + in: path + required: true + schema: + type: string + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + range-start: + description: The start date from when to pull Server telemetry data + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to pull Server telemetry data + $ref: '#/components/schemas/DateTime' + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of telemetry points. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/ServerStatsTelemetry' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}/telemetry/stream: + get: + operationId: getServerTelemetryStreamAuth + summary: Server Telemetry Stream Authorization + description: | + Retrieves an access token and URL to open a websocket to for streaming server telemetry live. + This connects directly to the server and streams telemetry in real time, with a new snapshot + pushed approximately every 10 seconds. + + Open a WebSocket to the returned `address`, passing the token as the `token` query parameter + (e.g. `wss://
?token=`). + + Requires the `servers-view` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID of the requested server. + in: path + required: true + schema: + type: string + pattern: ^[a-f0-9]{24}$ + responses: + '200': + description: Returns credentials for connecting to a server telemetry stream. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + description: Credentials for connecting to the server telemetry stream. + required: + - token + - address + properties: + token: + type: string + description: The authentication token, passed to the address as the `token` query parameter. + address: + type: string + description: The URL to open a websocket to for streaming server telemetry data. + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}/instances: + get: + operationId: getServerInstances + summary: List Server Instances + description: Requires the `containers-view` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID for the given server. + in: path + required: true + schema: + type: string + - $ref: '#/components/parameters/PageParam' + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creator + - servers + - locations + - integrations + - containers + - environments + responses: + '200': + description: Returns a list of Instances present on this Server. + content: + application/json: + schema: + title: GetServerInstancesReturn + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Instance' + includes: + $ref: '#/components/schemas/InstanceIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}/tasks: + post: + operationId: createServerJob + summary: Create Server Job + description: Used to perform different actions on a given Server. Requires the `servers-manage` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID for the given Server. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating the new Server Job. + content: + application/json: + schema: + $ref: '#/components/schemas/ServerTask' + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/tags: + get: + operationId: getServerTags + summary: List Server Tags + description: Requires the `servers-view` capability. + tags: + - Servers + parameters: + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + cluster: + type: string + description: | + `filter[cluster]=clusterone,clustertwo` filtering by cluster. Enter one or more clusters (commas separated) and the return will include tags from servers that match any cluster(s) in the list. + responses: + '200': + description: Returns a list of Server Tags. + content: + application/json: + schema: + $ref: '#/components/schemas/ServerTags' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/servers/{serverId}/console: + get: + operationId: GetServerConsole + summary: Get Server Console + description: | + Gets the authorization information required to connect to a Server console websocket. + + Requires the `servers-console` capability. + tags: + - Servers + parameters: + - name: serverId + description: The ID of the server to connect to. + in: path + required: true + schema: + type: string + responses: + '200': + description: Returns console credentials for the Server. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: object + required: + - address + - token + properties: + address: + type: string + description: The websocket target URL. + token: + type: string + description: The authentication token for the console socket. It should be appended as the URL parameter "token" to the address. + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/ips/pools: + post: + operationId: createIpPool + summary: Create IP Pool + description: | + Create an infrastructure IP Pool + + Requires the 'ips-manage' capability. + tags: + - IPs + parameters: [] + requestBody: + description: Parameters for creating a new IP pool. + content: + application/json: + schema: + type: object + required: + - server_id + - block + properties: + server_id: + $ref: '#/components/schemas/ID' + block: + type: object + required: + - cidr + - gateway + properties: + network: + oneOf: + - $ref: '#/components/schemas/Cidr' + - type: 'null' + cidr: + $ref: '#/components/schemas/Cidr' + gateway: + oneOf: + - $ref: '#/components/schemas/IpAddress' + - type: 'null' + options: + oneOf: + - $ref: '#/components/schemas/IpOptions' + - type: 'null' + responses: + '201': + description: Returns an IP Pool. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/IpPool' + default: + $ref: '#/components/responses/DefaultError' + get: + operationId: getIpPools + summary: List IP Pools + description: Requires the `ips-manage` capability. + tags: + - IPs + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - integrations + - locations + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + available: + type: string + description: | + `filter[available]=true` filter for IPs that are available for use. + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the IP's current state. + server: + type: string + description: | + `filter[server]=ID` server filtering by ID. Submit the ID of the server you wish to filter for and the return will be any IP pool associated with that server. + location: + type: string + description: | + `filter[location]=ID` location filtering by ID. Submit the ID of the location you wish to filter by. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: A list of IP Pools. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/IpPool' + includes: + $ref: '#/components/schemas/IpPoolIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/ips/pools/{poolId}: + get: + operationId: getIPPool + summary: Get IP Pool + description: Requires the `ips-manage` capability. + tags: + - IPs + parameters: + - name: poolId + description: The ID for the given pool. + in: path + required: true + schema: + type: string + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - servers + - integrations + - locations + responses: + '200': + description: An IP Pool. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/IpPool' + includes: + $ref: '#/components/schemas/IpPoolIncludes' + default: + $ref: '#/components/responses/DefaultError' + delete: + operationId: deleteIPPool + summary: Delete IP Pool + description: Requires the `ips-manage` capability. + tags: + - IPs + parameters: + - name: poolId + description: The ID for the given IP pool. + in: path + required: true + schema: + type: string + responses: + '202': + description: Returns a Job Descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/ips/pools/{poolId}/ips: + get: + operationId: getPoolIPs + summary: List Pool IPs + description: Requires the `infrastructure-ips-manage` capability. + tags: + - IPs + parameters: + - name: poolId + description: The ID of the IP Pool to fetch the IPs of. + in: path + required: true + schema: + type: string + responses: + '200': + description: A list of IPs. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Ip' + default: + $ref: '#/components/responses/DefaultError' + /v1/infrastructure/ips/pools/{poolId}/tasks: + post: + operationId: createIpPoolJob + summary: Create IP Pool Job + description: Used to perform different actions on a given IP pool. Requires the `ips-manage` capability. + tags: + - IPs + parameters: + - name: poolId + description: The ID for the given IP pool. + in: path + required: true + schema: + type: string + requestBody: + description: Parameters for creating the new IP pool job. + content: + application/json: + schema: + $ref: '#/components/schemas/IpPoolTask' + responses: + '202': + description: Returns a job descriptor. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/JobDescriptor' + default: + $ref: '#/components/responses/DefaultError' + /v1/jobs: + get: + operationId: getJobs + summary: List Jobs + description: Requires the `apionly-jobs-view` permission. + tags: + - Jobs + parameters: + - name: include + in: query + required: false + description: A comma separated list of include values. Included resources will show up under the root document's `include` field, with the key being the id of the included resource. In the case of applying an include to a collection of resources, if two resources share the same include, it will only appear once in the return. + schema: + type: array + items: + type: string + enum: + - creators + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + schema: + type: object + properties: + range-start: + description: The start date from when to fetch Jobs + $ref: '#/components/schemas/DateTime' + range-end: + description: The end date from when to fetch Jobs + $ref: '#/components/schemas/DateTime' + search: + type: string + description: | + `filter[search]=value` search jobs for a value associated with a field on the given job(s). + state: + type: string + description: | + `filter[state]=value1,value2` state filtering will allow you to filter by the job's current state. + - $ref: '#/components/parameters/SortParam' + - $ref: '#/components/parameters/PageParam' + responses: + '200': + description: Returns a list of Jobs. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Job' + includes: + $ref: '#/components/schemas/JobIncludes' + default: + $ref: '#/components/responses/DefaultError' + /v1/jobs/{jobId}: + get: + operationId: getJob + summary: Get Job + description: Requires the `apionly-jobs-view` permission. + tags: + - Jobs + parameters: + - name: jobId + description: The ID for the given Job. + in: path + required: true + schema: + type: string + responses: + '200': + description: A Job resources. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + $ref: '#/components/schemas/Job' + default: + $ref: '#/components/responses/DefaultError' + /v1/jobs/latest: + get: + operationId: getLatestJobs + tags: + - Jobs + parameters: [] + summary: List Latest Jobs + description: Requires the `apionly-jobs-view` permission. + responses: + '200': + description: Returns a list of Jobs. + content: + application/json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + $ref: '#/components/schemas/Job' + default: + $ref: '#/components/responses/DefaultError' + /v1/monitoring/metrics: + get: + operationId: getMetrics + summary: Get Metrics + description: | + A basic query for retrieving metrics. For a more complex and granular report, see the `/v1/monitoring/metrics/aggregate` endpoint. + + Requires the `monitor-view` capability. + tags: + - Monitoring + parameters: + - name: filter + in: query + style: deepObject + required: false + description: | + ## Filter Field + The filter field is a key-value object, where the key is what you would like to filter, and the value is the value you're filtering for. + + To search via labels, use `label: