Projects¶

Projects, their locations, and deleting or resuming them.

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.

List projects¶

GET /v1/orgs/{org_id}/projects

The projects the caller can see, with their location and state.

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

Responses

200 OK

application/jsonapplication/json

{
    "data_as_of": "2022-04-13T15:42:05.901Z",
    "items": [
        {
            "created_at": "2022-04-13T15:42:05.901Z",
            "desired_lifecycle_state": "string",
            "display_name": "string",
            "id": "string",
            "lifecycle_state": "string",
            "location": "string",
            "placements": [
                {
                    "conditions": [
                        {
                            "observed_at": "2022-04-13T15:42:05.901Z",
                            "reason": "string",
                            "status": "string",
                            "type": "string"
                        }
                    ],
                    "data_as_of": "2022-04-13T15:42:05.901Z",
                    "deletion": {
                        "blocked_reason": "string",
                        "cascade": true,
                        "release": true,
                        "released_at": "2022-04-13T15:42:05.901Z",
                        "retention_until": "2022-04-13T15:42:05.901Z",
                        "state": "string"
                    },
                    "generation": {
                        "desired": 0,
                        "observed": 0
                    },
                    "id": "string",
                    "lifecycle": {
                        "desired": "string",
                        "observed": "string"
                    },
                    "location": {
                        "display_name": "string",
                        "id": "string",
                        "slug": "string"
                    },
                    "provider": {
                        "keystone_project_id": "string"
                    },
                    "reason": "string",
                    "routing": {
                        "error": "string",
                        "id": "string",
                        "operation": "string",
                        "state": "string"
                    },
                    "status": "string",
                    "warnings": [
                        {
                            "reason": "string",
                            "type": "string"
                        }
                    ]
                }
            ],
            "slug": "string"
        }
    ]
}

422 Unprocessable Entity

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

Create a project¶

POST /v1/orgs/{org_id}/projects

Creates a project in one location, with private routing and, if asked, a ready network there. A project's location never changes. 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

Request body

application/json202 Accepted

{
    "display_name": "string",
    "location": "string",
    "network": {
        "cidr": "string",
        "dns_nameservers": [
            "string"
        ],
        "internet_gateway": true
    },
    "quota_profile": "string",
    "slug": "string"
}

Responses

application/jsonapplication/json

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

422 Unprocessable Entity

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

Delete a project¶

DELETE /v1/orgs/{org_id}/projects/{project_id}

Starts the project's deletion: it is suspended and kept for the retention period, during which the deletion can be cancelled. Needs a recent second-factor sign-in. 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

{
    "cascade": true,
    "confirmed_report": {}
}

Responses

application/jsonapplication/json

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

422 Unprocessable Entity

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

Get a project¶

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

One project with its location, its state there and the caller's role.

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

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "data_as_of": "2022-04-13T15:42:05.901Z",
    "desired_lifecycle_state": "string",
    "display_name": "string",
    "id": "string",
    "lifecycle_state": "string",
    "location": "string",
    "placements": [
        {
            "conditions": [
                {
                    "observed_at": "2022-04-13T15:42:05.901Z",
                    "reason": "string",
                    "status": "string",
                    "type": "string"
                }
            ],
            "data_as_of": "2022-04-13T15:42:05.901Z",
            "deletion": {
                "blocked_reason": "string",
                "cascade": true,
                "release": true,
                "released_at": "2022-04-13T15:42:05.901Z",
                "retention_until": "2022-04-13T15:42:05.901Z",
                "state": "string"
            },
            "generation": {
                "desired": 0,
                "observed": 0
            },
            "id": "string",
            "lifecycle": {
                "desired": "string",
                "observed": "string"
            },
            "location": {
                "display_name": "string",
                "id": "string",
                "slug": "string"
            },
            "provider": {
                "keystone_project_id": "string"
            },
            "reason": "string",
            "routing": {
                "error": "string",
                "id": "string",
                "operation": "string",
                "state": "string"
            },
            "status": "string",
            "warnings": [
                {
                    "reason": "string",
                    "type": "string"
                }
            ]
        }
    ],
    "slug": "string",
    "your_role": "string"
}

422 Unprocessable Entity

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

Get a project's deletion report¶

GET /v1/orgs/{org_id}/projects/{project_id}/deletion-report

What deleting the project would remove, counted per location and resource type, with how long it is kept before anything is destroyed. Confirm these counts when you delete it.

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

{
    "data_as_of": "2022-04-13T15:42:05.901Z",
    "placements": [
        {
            "counts": {},
            "empty": true,
            "externally_visible": [
                {
                    "display_name": "string",
                    "id": "string",
                    "type": "string",
                    "visibility": "string"
                }
            ],
            "location": "string",
            "placement_id": "string"
        }
    ],
    "retention_s": 0,
    "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 your personal service account¶

GET /v1/orgs/{org_id}/projects/{project_id}/personal-service-account

Your own service account on this project, if you have one (else 404).

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

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "description": "string",
    "display_name": "string",
    "grants": [
        {
            "id": "string",
            "project_id": "string",
            "project_name": "string",
            "role": "string"
        }
    ],
    "id": "string",
    "kind": "string",
    "native_identities": [
        {
            "deployment": "string",
            "groups": 0,
            "observed_at": "2022-04-13T15:42:05.901Z",
            "state": "string"
        }
    ],
    "owner_id": "string",
    "project_id": "string",
    "role": "string",
    "status": "string",
    "version": 0
}

422 Unprocessable Entity

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

Create your personal service account¶

POST /v1/orgs/{org_id}/projects/{project_id}/personal-service-account

Creates your own service account on this project, with member access here only. Its keys and location credentials last 30 days at most and end with your access to the project. One per person and project.

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

{
    "description": "string",
    "display_name": "string"
}

Responses

application/jsonapplication/json

{
    "created_at": "2022-04-13T15:42:05.901Z",
    "created_by": "string",
    "description": "string",
    "display_name": "string",
    "id": "string",
    "kind": "string",
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    },
    "owner_id": "string",
    "project_id": "string",
    "role": "string",
    "status": "string",
    "version": 0
}

422 Unprocessable Entity

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

Remove a location from a project¶

DELETE /v1/orgs/{org_id}/projects/{project_id}/placements/{placement_id}

Starts removing the project from one location, with the same retention and cancellation as a project's deletion. 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
`placement_id`	path	string		No
`project_id`	path	string		No

Request body

application/json202 Accepted

{
    "cascade": true,
    "confirmed_report": {}
}

Responses

application/jsonapplication/json

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

422 Unprocessable Entity

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

Cancel a location's removal¶

POST /v1/orgs/{org_id}/projects/{project_id}/placements/{placement_id}:cancel-deletion

Stops removing the project from this location, while nothing has been destroyed there yet. 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
`placement_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"
        }
    ]
}

Confirm a blocked removal¶

POST /v1/orgs/{org_id}/projects/{project_id}/placements/{placement_id}:confirm-deletion

A removal stopped because resources were still there, or because the report changed, continues once you confirm the counts it now shows. Needs a recent second-factor sign-in.

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
`placement_id`	path	string		No
`project_id`	path	string		No

Request body

application/json200 OK

{
    "confirmed_report": {}
}

Responses

application/jsonapplication/json

{
    "confirmed": true,
    "placement_id": "string"
}

422 Unprocessable Entity

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

Resume a project in one location¶

POST /v1/orgs/{org_id}/projects/{project_id}/placements/{placement_id}:resume

Makes the project active again in one location. 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
`placement_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"
        }
    ]
}

Cancel a project's deletion¶

POST /v1/orgs/{org_id}/projects/{project_id}:cancel-deletion

Stops a deletion that has not started destroying resources and keeps the project suspended until it is resumed. 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

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"
        }
    ]
}

End a deletion's retention early¶

POST /v1/orgs/{org_id}/projects/{project_id}:delete-now

Lets a deletion that is waiting out its retention period go ahead now. Needs the project's short name typed as confirmation and a recent second-factor sign-in.

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/json200 OK

{
    "confirm": "string"
}

Responses

application/jsonapplication/json

{
    "locations": 0,
    "project": "string"
}

422 Unprocessable Entity

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

Resume a project¶

POST /v1/orgs/{org_id}/projects/{project_id}:resume

Makes a suspended project active again, with its access in each location. 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

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

AccountProjectRole¶

Name	Type	Description
`id`	string	The grant (`grt_…`).
`project_id`	string
`project_name`	string
`role`	string

CollectionSource¶

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

ConfirmBody¶

Name	Type	Description
`confirmed_report`

ConfirmedRemoval¶

Name	Type	Description
`confirmed`	boolean
`placement_id`	string

DeleteBody¶

Name	Type	Description
`cascade`	boolean
`confirmed_report`

DeleteNowBody¶

Name	Type	Description
`confirm`	string

DeletionReport¶

Name	Type	Description
`data_as_of`	string(date-time) \| null
`placements`	Array<PlacementReportView>
`retention_s`	integer	How long, in seconds, the data is kept first.
`sources`	Array<CollectionSource>	How fresh each location's counts are.

Generation¶

Name	Type	Description
`desired`	integer
`observed`	integer

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

Lifecycle¶

Name	Type	Description
`desired`	string
`observed`	string \| null

NativeIdentity¶

Name	Type	Description
`deployment`	string
`groups`	integer	How many of its project groups it is in there.
`observed_at`	string(date-time)
`state`	string

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

PersonalBody¶

Name	Type	Description
`description`	string
`display_name`	string \| null

PersonalServiceAccount¶

Name	Type	Description
`created_at`	string(date-time)
`created_by`	string
`description`	string
`display_name`	string
`id`	string	The service account (`sa_…`).
`kind`	string	`organization`, or `personal` (one person's, one project).
`operation`	OperationLink	Its access to the project being set up in each location.
`owner_id`	string \| null	A personal account's owner (`usr_…`).
`project_id`	string \| null	A personal account's project.
`role`	string \| null	Its organization role.
`status`	string
`version`	integer	Its version, also its `ETag`.

PlacementCondition¶

Name	Type	Description
`observed_at`	string(date-time)
`reason`	string \| null
`status`	string
`type`	string

PlacementDeletion¶

Name	Type	Description
`blocked_reason`	string \| null
`cascade`	boolean
`release`	boolean	Whether instances and networking go as retention starts; data is kept.
`released_at`	string(date-time) \| null
`retention_until`	string(date-time)	Until when nothing is destroyed.
`state`	string

PlacementLocation¶

Name	Type	Description
`display_name`	string
`id`	string
`slug`	string

PlacementProvider¶

Name	Type	Description
`keystone_project_id`	string \| null	The project's ID in the location.

PlacementReportView¶

Name	Type	Description
`counts`		Per resource type; confirm these when deleting.
`empty`	boolean
`externally_visible`	Array<VisibleResource>
`location`	string
`placement_id`	string

PlacementRouting¶

Name	Type	Description
`error`	string \| null
`id`	string	The router (`rtr_…`).
`operation`	string \| null	The operation that last changed it (`op_…`).
`state`	string

PlacementWarning¶

Name	Type	Description
`reason`	string \| null
`type`	string

Project¶

Name	Type	Description
`created_at`	string(date-time)
`desired_lifecycle_state`	string
`display_name`	string
`id`	string	The project (`prj_…`).
`lifecycle_state`	string	Such as `active`, `suspended`, `deletion_requested`, `retention` or `deleting`.
`location`	string	The slug of the location the project lives in. A project placed in two locations reads the earliest one it is not being removed from.
`placements`	Array<ProjectPlacement>
`slug`	string

ProjectCreate¶

Name	Type	Description
`display_name`	string
`location`	string	The location the project lives in (`loc_…`).
`network`	ProjectNetwork
`quota_profile`	string \| null
`slug`	string

ProjectList¶

Name	Type	Description
`data_as_of`	string(date-time)
`items`	Array<Project>

ProjectNetwork¶

Name	Type	Description
`cidr`	string
`dns_nameservers`	Array<string>
`internet_gateway`	boolean

ProjectPlacement¶

Name	Type	Description
`conditions`	Array<PlacementCondition>
`data_as_of`	string(date-time)
`deletion`	PlacementDeletion
`generation`	Generation
`id`	string	The placement (`plc_…`).
`lifecycle`	Lifecycle
`location`	PlacementLocation
`provider`	PlacementProvider
`reason`	string \| null
`routing`	PlacementRouting
`status`	string	`provisioning`, `ready`, `error` or `blocked`.
`warnings`	Array<PlacementWarning>

ProjectView¶

Name	Type	Description
`created_at`	string(date-time)
`data_as_of`	string(date-time)
`desired_lifecycle_state`	string
`display_name`	string
`id`	string	The project (`prj_…`).
`lifecycle_state`	string	Such as `active`, `suspended`, `deletion_requested`, `retention` or `deleting`.
`location`	string	The slug of the location the project lives in. A project placed in two locations reads the earliest one it is not being removed from.
`placements`	Array<ProjectPlacement>
`slug`	string
`your_role`	string \| null	The caller's project role; null: none.

RetentionEnded¶

Name	Type	Description
`locations`	integer	How many locations it now goes ahead in.
`project`	string

ServiceAccountDetail¶

Name	Type	Description
`created_at`	string(date-time)
`created_by`	string
`description`	string
`display_name`	string
`grants`	Array<AccountProjectRole>
`id`	string	The service account (`sa_…`).
`kind`	string	`organization`, or `personal` (one person's, one project).
`native_identities`	Array<NativeIdentity>
`owner_id`	string \| null	A personal account's owner (`usr_…`).
`project_id`	string \| null	A personal account's project.
`role`	string \| null	Its organization role.
`status`	string
`version`	integer	Its version, also its `ETag`.

SourceProblem¶

Name	Type	Description
`code`	string \| null
`title`	string
`type`	string

ValidationError¶

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

VisibleResource¶

Name	Type	Description
`display_name`	string \| null
`id`	string
`type`	string
`visibility`	string