Resources

Lists, reads, attachments and activity of any resource type.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

Get a project's inventory summary

GET /v1/orgs/{org_id}/projects/{project_id}/inventory

How many resources of each type the project has in each location, and how fresh that information is.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "complete": true,
    "counts": [
        {
            "count": 0,
            "location": "string",
            "resource_type": "string"
        }
    ],
    "sources": [
        {
            "data_as_of": "string",
            "last_success_at": "string",
            "location": "string",
            "problem": {
                "code": "string",
                "title": "string",
                "type": "string"
            },
            "service": "string",
            "status": "ok"
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Check a project's resources now

POST /v1/orgs/{org_id}/projects/{project_id}/inventory:refresh

Asks each location to read the project's resources again instead of waiting for the next regular check. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
idempotency-key	header	string		Yes
org_id	path	string		No
project_id	path	string		No

Request body

application/json202 Accepted

{
    "locations": [
        "string"
    ],
    "resource_types": [
        "server"
    ]
}

Responses

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List a project's resources

GET /v1/orgs/{org_id}/projects/{project_id}/{collection}

Instances, volumes, networks or another resource type of the project across its locations, as last read from each, a page at a time. sources says how fresh each location's data is.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
cursor	query	string		Yes
display_name_prefix	query	string		Yes
limit	query	integer		Yes
location	query	string		Yes
org_id	path	string		No
project_id	path	string		No
status	query	string		Yes
tag	query	array		Yes	key:value, repeatable: only resources with every one of these NubeStack Cloud tags.
tag_key	query	string		Yes	Only resources with a NubeStack Cloud tag of this key.

Responses

200 OK

application/jsonapplication/json

{
    "complete": true,
    "items": [
        {
            "active_operation": {
                "id": "string",
                "kind": "string",
                "setting_up": true
            },
            "attributes": {},
            "connections": [
                {
                    "peer_id": "string",
                    "pending": true,
                    "router_id": "string"
                }
            ],
            "created_at": "2022-04-13T15:42:05.901Z",
            "display_name": "string",
            "error": "string",
            "id": "string",
            "image_source": {
                "address": "string",
                "instance_id": "string",
                "kind": "string"
            },
            "internet_access": {
                "enabled": true,
                "observed_gateway": true,
                "pending": true,
                "project_gateway": true,
                "router_id": "string"
            },
            "internet_gateway": {
                "addresses": [
                    null
                ],
                "desired": true,
                "enabled": true,
                "pending": true,
                "snat_enabled": true,
                "state": "string"
            },
            "last_operation": "string",
            "lb_certificates": [
                {
                    "certificate_id": "string",
                    "role": "default"
                }
            ],
            "lb_change_pending": true,
            "lb_configuration": {
                "values": {},
                "version": "string"
            },
            "lb_features": {
                "algorithms": [
                    "string"
                ],
                "member_weight": true,
                "monitor_bounds": {
                    "delay_max": 0,
                    "delay_min": 0,
                    "max_retries_max": 0,
                    "max_retries_min": 0,
                    "timeout_below_delay": true,
                    "timeout_min": 0,
                    "udp_connect_delay_min": 0
                },
                "monitors": [
                    "string"
                ],
                "monitors_by_protocol": {},
                "pool_protocols": {},
                "protocols": [
                    "string"
                ],
                "tls_passthrough": [
                    "string"
                ],
                "tls_termination": [
                    "string"
                ],
                "version": "string"
            },
            "lb_members": {
                "values": [
                    {
                        "address": "string",
                        "backup": true,
                        "enabled": true,
                        "port": 0,
                        "weight": 0
                    }
                ],
                "version": "string"
            },
            "lb_parent_id": "string",
            "location": "string",
            "managed_for": "string",
            "observation": {
                "data_as_of": "2022-04-13T15:42:05.901Z",
                "lifecycle": "string",
                "observed_at": "2022-04-13T15:42:05.901Z",
                "source": "collector",
                "source_status": "string",
                "stale": true,
                "status": "string"
            },
            "org_id": "string",
            "origin": "string",
            "phase": "string",
            "private_router": true,
            "project_gateway": true,
            "project_id": "string",
            "provider": {
                "deployment": "string",
                "id": "string",
                "region": "string"
            },
            "routing": {
                "enabled": true,
                "pending": true,
                "router_id": "string"
            },
            "status": "string",
            "tags": {},
            "tags_drift": {
                "cloud": {},
                "observed_at": "2022-04-13T15:42:05.901Z"
            },
            "tags_version": "string",
            "type": "string"
        }
    ],
    "next_cursor": "string",
    "sources": [
        {
            "data_as_of": "string",
            "last_success_at": "string",
            "location": "string",
            "problem": {
                "code": "string",
                "title": "string",
                "type": "string"
            },
            "service": "string",
            "status": "ok"
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a resource

GET /v1/orgs/{org_id}/projects/{project_id}/{collection}/{item_id}

One resource as last read from its location, with its status, attributes, whether NubeStack Cloud made it, and when it was read.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
item_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "active_operation": {
        "id": "string",
        "kind": "string",
        "setting_up": true
    },
    "attributes": {},
    "connections": [
        {
            "peer_id": "string",
            "pending": true,
            "router_id": "string"
        }
    ],
    "created_at": "2022-04-13T15:42:05.901Z",
    "display_name": "string",
    "error": "string",
    "id": "string",
    "image_source": {
        "address": "string",
        "instance_id": "string",
        "kind": "string"
    },
    "internet_access": {
        "enabled": true,
        "observed_gateway": true,
        "pending": true,
        "project_gateway": true,
        "router_id": "string"
    },
    "internet_gateway": {
        "addresses": [
            null
        ],
        "desired": true,
        "enabled": true,
        "pending": true,
        "snat_enabled": true,
        "state": "string"
    },
    "last_operation": "string",
    "lb_certificates": [
        {
            "certificate_id": "string",
            "role": "default"
        }
    ],
    "lb_change_pending": true,
    "lb_configuration": {
        "values": {},
        "version": "string"
    },
    "lb_features": {
        "algorithms": [
            "string"
        ],
        "member_weight": true,
        "monitor_bounds": {
            "delay_max": 0,
            "delay_min": 0,
            "max_retries_max": 0,
            "max_retries_min": 0,
            "timeout_below_delay": true,
            "timeout_min": 0,
            "udp_connect_delay_min": 0
        },
        "monitors": [
            "string"
        ],
        "monitors_by_protocol": {},
        "pool_protocols": {},
        "protocols": [
            "string"
        ],
        "tls_passthrough": [
            "string"
        ],
        "tls_termination": [
            "string"
        ],
        "version": "string"
    },
    "lb_members": {
        "values": [
            {
                "address": "string",
                "backup": true,
                "enabled": true,
                "port": 0,
                "weight": 0
            }
        ],
        "version": "string"
    },
    "lb_parent_id": "string",
    "location": "string",
    "managed_for": "string",
    "observation": {
        "data_as_of": "2022-04-13T15:42:05.901Z",
        "lifecycle": "string",
        "observed_at": "2022-04-13T15:42:05.901Z",
        "source": "collector",
        "source_status": "string",
        "stale": true,
        "status": "string"
    },
    "org_id": "string",
    "origin": "string",
    "phase": "string",
    "private_router": true,
    "project_gateway": true,
    "project_id": "string",
    "provider": {
        "deployment": "string",
        "id": "string",
        "region": "string"
    },
    "routing": {
        "enabled": true,
        "pending": true,
        "router_id": "string"
    },
    "status": "string",
    "tags": {},
    "tags_drift": {
        "cloud": {},
        "observed_at": "2022-04-13T15:42:05.901Z"
    },
    "tags_version": "string",
    "type": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a resource's activity

GET /v1/orgs/{org_id}/projects/{project_id}/{collection}/{item_id}/activity

The newest operations that created, changed or referred to the resource, with the state of each step.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
item_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "items": [
        {
            "accepted_at": "2022-04-13T15:42:05.901Z",
            "actor": {
                "email": "string",
                "id": "string",
                "kind": "person",
                "name": "string",
                "you": true
            },
            "completed_at": "2022-04-13T15:42:05.901Z",
            "error": {
                "code": "string"
            },
            "id": "string",
            "kind": "string",
            "role": "target",
            "started_at": "2022-04-13T15:42:05.901Z",
            "state": "string",
            "steps": [
                {
                    "action": "string",
                    "attempts": 0,
                    "completed_at": "2022-04-13T15:42:05.901Z",
                    "error": null,
                    "ordinal": 0,
                    "region": "string",
                    "result": {},
                    "service": "string",
                    "started_at": "2022-04-13T15:42:05.901Z",
                    "state": "string"
                }
            ]
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Get a resource's attachments

GET /v1/orgs/{org_id}/projects/{project_id}/{collection}/{item_id}/related

What the resource is attached to or holds, such as the instances using a security group, a volume's instance or a network's subnets.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
item_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "relations": [
        {
            "items": [
                {
                    "active_operation": {
                        "id": "string",
                        "kind": "string",
                        "setting_up": true
                    },
                    "attributes": {},
                    "connections": [
                        {
                            "peer_id": "string",
                            "pending": true,
                            "router_id": "string"
                        }
                    ],
                    "created_at": "2022-04-13T15:42:05.901Z",
                    "display_name": "string",
                    "error": "string",
                    "id": "string",
                    "image_source": {
                        "address": "string",
                        "instance_id": "string",
                        "kind": "string"
                    },
                    "internet_access": {
                        "enabled": true,
                        "observed_gateway": true,
                        "pending": true,
                        "project_gateway": true,
                        "router_id": "string"
                    },
                    "internet_gateway": {
                        "addresses": [
                            null
                        ],
                        "desired": true,
                        "enabled": true,
                        "pending": true,
                        "snat_enabled": true,
                        "state": "string"
                    },
                    "last_operation": "string",
                    "lb_certificates": [
                        {
                            "certificate_id": "string",
                            "role": "default"
                        }
                    ],
                    "lb_change_pending": true,
                    "lb_configuration": {
                        "values": {},
                        "version": "string"
                    },
                    "lb_features": {
                        "algorithms": [
                            "string"
                        ],
                        "member_weight": true,
                        "monitor_bounds": {
                            "delay_max": 0,
                            "delay_min": 0,
                            "max_retries_max": 0,
                            "max_retries_min": 0,
                            "timeout_below_delay": true,
                            "timeout_min": 0,
                            "udp_connect_delay_min": 0
                        },
                        "monitors": [
                            "string"
                        ],
                        "monitors_by_protocol": {},
                        "pool_protocols": {},
                        "protocols": [
                            "string"
                        ],
                        "tls_passthrough": [
                            "string"
                        ],
                        "tls_termination": [
                            "string"
                        ],
                        "version": "string"
                    },
                    "lb_members": {
                        "values": [
                            {
                                "address": "string",
                                "backup": true,
                                "enabled": true,
                                "port": 0,
                                "weight": 0
                            }
                        ],
                        "version": "string"
                    },
                    "lb_parent_id": "string",
                    "location": "string",
                    "managed_for": "string",
                    "observation": {
                        "data_as_of": "2022-04-13T15:42:05.901Z",
                        "lifecycle": "string",
                        "observed_at": "2022-04-13T15:42:05.901Z",
                        "source": "collector",
                        "source_status": "string",
                        "stale": true,
                        "status": "string"
                    },
                    "org_id": "string",
                    "origin": "string",
                    "phase": "string",
                    "private_router": true,
                    "project_gateway": true,
                    "project_id": "string",
                    "provider": {
                        "deployment": "string",
                        "id": "string",
                        "region": "string"
                    },
                    "routing": {
                        "enabled": true,
                        "pending": true,
                        "router_id": "string"
                    },
                    "status": "string",
                    "tags": {},
                    "tags_drift": {
                        "cloud": {},
                        "observed_at": "2022-04-13T15:42:05.901Z"
                    },
                    "tags_version": "string",
                    "type": "string"
                }
            ],
            "relation": "string",
            "type": "string",
            "withheld": true
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Dismiss a failed create

POST /v1/orgs/{org_id}/projects/{project_id}/{collection}/{item_id}:dismiss

Removes a resource whose creation failed before anything was made in the location from the lists. Nothing is sent to the location.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
idempotency-key	header	string		Yes
item_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "dismissed": true,
    "id": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Check a resource now

POST /v1/orgs/{org_id}/projects/{project_id}/{collection}/{item_id}:refresh

Asks the location to read this resource again. Accepted at once: follow the returned operation until it finishes.

Input parameters

Parameter	In	Type	Default	Nullable	Description
Authorization	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
collection	path	string		No
idempotency-key	header	string		Yes
item_id	path	string		No
org_id	path	string		No
project_id	path	string		No

Responses

202 Accepted

application/jsonapplication/json

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

---

Schemas

Accepted

Name	Type	Description
operation	OperationLink

ActiveOperation

Name	Type	Description
id	string	The operation (op_…).
kind	string
setting_up	boolean	True while it is the resource's own create, still finishing (a network's range being attached to the private router, say); false for a change to it.

Activity

Name	Type	Description
id	string
items	Array<ResourceOperation>

ActorRef

Name	Type	Description
email	string	A member's address, only to a caller who manages members.
id	string | null	The person (usr_…); null for NubeStack Cloud itself.
kind	string	A member of this organization, one of its service accounts, someone who has left it, or NubeStack Cloud itself (its own work, or its staff).
name	string | null	A member's display name or a service account's name, to a caller who may see the members; otherwise null.
you	boolean	Whether it was the caller.

CollectionSource

Name	Type	Description
data_as_of	string | null
last_success_at	string | null
location	string
problem	SourceProblem
service	string
status	string

Dismissed

Name	Type	Description
dismissed	boolean
id	string

ErrorCode

Name	Type	Description
code	string	The problem code, as in the error catalogue.

HTTPValidationError

Name	Type	Description
detail	Array<ValidationError>

ImageSource

Name	Type	Description
address	string | null	An imported image: its address.
instance_id	string | null	An instance's image: the instance it was saved from.
kind	string	instance, address or outside (native tools).

InventoryItem

Name	Type	Description
active_operation	ActiveOperation	The operation acting on the resource now (one at a time), or null. A resource the cloud reads as active is still being set up or changed while this is set: a network just created, say, while its range is attached to the private router.
attributes		Its properties as the location reports them.
connections	Array<NetworkConnection>
created_at	string(date-time) | null
display_name	string | null
error	string | null
id	string
image_source	ImageSource
internet_access	NetworkInternetAccess
internet_gateway	RouterInternetGateway
last_operation	string | null
lb_certificates	Array<LbListenerCertificate>	A listener: the certificates it serves, the default first.
lb_change_pending	boolean
lb_configuration	LbConfiguration
lb_features	LbFeatures
lb_members	LbMembers	A pool: its newest member list NubeStack Cloud can trust, or null.
lb_parent_id	string | null
location	string
managed_for	string | null	A router: the network it is the gateway of, or null.
observation	Observation
org_id	string
origin	string	broker: made through NubeStack Cloud; native: made with the location's own tools.
phase	string | null	The state of NubeStack Cloud's own commands on it.
private_router	boolean
project_gateway	boolean
project_id	string
provider	ProviderRef
routing	NetworkRouting
status	string | null
tags		An instance, volume, network or public IP: its NubeStack Cloud tags.
tags_drift	TagDrift	Set when the location shows other nx. tags than NubeStack Cloud keeps: they were changed outside NubeStack Cloud (or NubeStack Cloud's last write failed). Null when they agree or are being written.
tags_version	string | null	The tags' version, sent in If-Match to change them.
type	string

InventoryPage

Name	Type	Description
complete	boolean	True when every source is healthy; independent of pagination.
items	Array<InventoryItem>
next_cursor	string | null	Cursor for the next page; null ends pagination.
sources	Array<CollectionSource>

InventorySummary

Name	Type	Description
complete	boolean	Whether every location's data is fresh.
counts	Array<ResourceCount>
sources	Array<CollectionSource>

LbConfiguration

Name	Type	Description
values
version	string	Name it as expected when changing the configuration.

LbFeatures

Name	Type	Description
algorithms	Array<string>
member_weight	boolean | null	Whether members may have different weights.
monitor_bounds	LbMonitorBounds
monitors	Array<string>	Every health-check type, whatever the protocol.
monitors_by_protocol		The health-check types a pool of each protocol takes.
pool_protocols		The protocol a listener's pool speaks, by listener protocol (a TLS-terminating listener's pool speaks HTTP).
protocols	Array<string>
tls_passthrough	Array<string>	Protocols whose TLS passes through to the instances; never TLS termination.
tls_termination	Array<string>	Protocols that terminate TLS with one of the project's certificates; offered only where the location has a key manager.
version	string | null	The feature table's version.

LbListenerCertificate

Name	Type	Description
certificate_id	string | null	crt_…; null for a secret that was not uploaded through NubeStack Cloud.
role	string	default: served when no other certificate covers the host name the client asks for; sni: served only to a client asking for one of its names.

LbMember

Name	Type	Description
address	string
backup	boolean
enabled	boolean
port	integer | null
weight	integer

LbMembers

Name	Type	Description
values	Array<LbMember>
version	string	Name it as expected when replacing the members.

LbMonitorBounds

Name	Type	Description
delay_max	integer
delay_min	integer
max_retries_max	integer
max_retries_min	integer
timeout_below_delay	boolean	The timeout must be shorter than the delay.
timeout_min	integer
udp_connect_delay_min	integer

NetworkConnection

Name	Type	Description
peer_id	string	The network it is connected to (net_…).
pending	boolean
router_id	string

NetworkInternetAccess

Name	Type	Description
enabled	boolean
observed_gateway	boolean
pending	boolean
project_gateway	boolean	Whether it is through the project's own router.
router_id	string | null

NetworkRouting

Name	Type	Description
enabled	boolean
pending	boolean
router_id	string | null

Observation

Name	Type	Description
data_as_of	string(date-time) | null
lifecycle	string	Such as creating, present, missing or create_failed.
observed_at	string(date-time) | null
source	string	collector: the location's regular read; operation: NubeStack Cloud's own command, before the location has been read since.
source_status	string
stale	boolean
status	string	What the command itself read, when it read one.

OperationLink

Name	Type	Description
href	string	Where to read the operation; also the Location header.
id	string	The operation's ID (op_…).
state	string | null	Its state when accepted, normally queued.

ProviderRef

Name	Type	Description
deployment	string
id	string | null	Its ID in the location, once it has one.
region	string

RefreshBody

Name	Type	Description
locations	Array<string>
resource_types	Array<ResourceType>

Related

Name	Type	Description
id	string
relations	Array<Relation>

Relation

Name	Type	Description
items	Array<InventoryItem>
relation	string	Such as servers, volumes or subnets.
type	string
withheld	boolean	True when the location's data cannot be shown now.

ResourceCount

Name	Type	Description
count	integer
location	string
resource_type	string

ResourceOperation

Name	Type	Description
accepted_at	string(date-time)
actor	ActorRef
completed_at	string(date-time) | null
error	ErrorCode
id	string	The operation (op_…).
kind	string
role	string	Whether the operation acted on the resource or only named it.
started_at	string(date-time) | null
state	string
steps	Array<StepCall>

ResourceType

Type: string

RouterInternetGateway

Name	Type	Description
addresses	Array<>	Its public addresses.
desired	boolean | null
enabled	boolean
pending	boolean
snat_enabled	boolean | null
state	string	creating, deleting, active, absent or unknown.

SourceProblem

Name	Type	Description
code	string | null
title	string
type	string

StepCall

Name	Type	Description
action	string | null	What the step does, such as create_server.
attempts	integer
completed_at	string(date-time) | null
error	ErrorCode
ordinal	integer
region	string | null
result		The identifiers the step recorded, such as the provider ID it created.
service	string | null
started_at	string(date-time) | null
state	string

TagDrift

Name	Type	Description
cloud		The nx. tags read from the location.
observed_at	string(date-time) | null

ValidationError

Name	Type	Description
ctx
input
loc	Array<>
msg	string
type	string