logo

Cycle Infrastructure Abstraction Layer (1.0.0)

Download OpenAPI specification:Download

E-mail: support@cycle.io License: Apache-2.0

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.

For a Go implementation of the types, see the repo available here: https://github.com/cycleplatform/integrations

Auth

Verify Auth

Cycle will utilize this endpoint to verify that user-specified credentials can properly authorize with the IAL integration.

Request
Request Body schema: application/json
required
object (Auth)

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.

request
required
null
Responses
200

Returns an object with a valid property. Should be true if the authorization is successful.

post/v1/auth/verify
Request samples
application/json
{
  • "auth": {
    },
  • "request": null
}
Response samples
application/json
{
  • "valid": true
}

Provider

List Locations

Cycle will utilize this call to learn which locations it is able to deploy servers to.

Responses
200

Returns a list of available server locations for this IAL.

get/v1/infrastructure/provider/locations
Response samples
application/json
{
  • "locations": [
    ],
  • "extra": {
    }
}

List Server Models

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).

Responses
200

Returns a list of available server models available via this IAL integration.

get/v1/infrastructure/provider/server-models
Response samples
application/json
{
  • "models": [
    ],
  • "extra": {
    }
}

Location

Configure Location

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.

Request
Request Body schema: application/json
required
object (Auth)

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.

required
object

A request to update or configure the settings for a specific location.

Responses
200

Returns the updated location configuration.

post/v1/location/configure
Request samples
application/json
{
  • "auth": {
    },
  • "request": {
    }
}
Response samples
application/json
{
  • "configured": true,
  • "version": "string",
  • "configuration_latest": { }
}

Server

Provision Server

Cycle will utilize this endpoint to start the provision of a server.

Request
Request Body schema: application/json
required
object (Auth)

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.

required
object

Properties for initiating a server provision.

Responses
200

Returns details about the server being provisioned.

post/v1/infrastructure/server/provision
Request samples
application/json
{
  • "auth": {
    },
  • "request": {
    }
}
Response samples
application/json
{
  • "server_id": "string",
  • "extra": { }
}

Get Provision Server Status

Cycle will use this endpoint to track the status of a provision and, when complete, authorize a server to pull CycleOS via IPXE.

Responses
200

Returns the status of a server provisioning request, including server ID, provisioning status, authentication details, and any additional extra information.

get/v1/infrastructure/server/provision-status
Response samples
application/json
{
  • "server_id": "string",
  • "provisioned": true,
  • "auth": {
    },
  • "extra": { }
}

Decommission Server

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.

Request
Request Body schema: application/json
required
object (Auth)

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.

required
object

Represents a request to decommission a server, including server identification details, location, and any extra information required by the provider or for internal processes.

Responses
200

Returns a boolean of the success of the decommission.

post/v1/infrastructure/server/decommission
Request samples
application/json
{
  • "auth": {
    },
  • "request": {
    }
}
Response samples
application/json
true

Restart Server

Cycle will call this endpoint whenever a request has been made via the platform to restart a server.

Request
Request Body schema: application/json
required
object (Auth)

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.

required
object

Describes a request to restart a server.

Responses
200

Returns a boolean of the success of the restart.

post/v1/infrastructure/server/restart
Request samples
application/json
{
  • "auth": {
    },
  • "request": {
    }
}
Response samples
application/json
true

IP

Allocate IP Address

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).

Request
Request Body schema: application/json
required
object (Auth)

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.

required
object

Represents a request to allocate an IP address, detailing the kind of IP, relevant server and location identifiers, and configuration details.

Responses
200

Returns information about the allocated IP address.

post/v1/infrastructure/ip/allocate
Request samples
application/json
{
  • "auth": {
    },
  • "request": {
    }
}
Response samples
application/json
{
  • "ip_id": "string",
  • "ip_assignment_id": "string",
  • "cidr": "string",
  • "gateway": "string",
  • "netmask": "string",
  • "network": "string",
  • "nat_private_ip": "string"
}

Release IP Address

When an IP is no longer needed, Cycle will release it using this API endpoint.

Request
Request Body schema: application/json
required
kind
required
string (IPKind)

The kind (IPv4 or IPv6) of an IP.

Enum: "ipv4" "ipv6"
ip_id
required
string

The unique identifier of the IP at the provider.

ip_assignment_id
required
string

The unique identifier of the IP assignment at the provider.

cidr
required
string

The CIDR notation of the IP address being released.

nat_private_ip
string or null

The private IP address used for NAT (Network Address Translation), if applicable.

zone_id
string or null

The identifier of the zone within the location, if applicable.

server_id
required
string

The unique identifier of the server associated with the IP.

location_id
required
string

The identifier of the location where the IP was used.

required
object

Configuration details specific to the location from which the IP is being released.

required
object (CycleIPMeta)

Metadata associated with an IP within Cycle.

Responses
200

Returns a boolean of the success of the release.

post/v1/infrastructure/ip/release
Request samples
application/json
{
  • "kind": "ipv4",
  • "ip_id": "string",
  • "ip_assignment_id": "string",
  • "cidr": "string",
  • "nat_private_ip": "string",
  • "zone_id": "string",
  • "server_id": "string",
  • "location_id": "string",
  • "location_configuration": { },
  • "cycle": {
    }
}
Response samples
application/json
true