Organizations¶

Who you are, your organization, its settings, locations and catalog, and closing it.

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.

Who am I¶

GET /v1/me

The signed-in person or service account, with every organization they belong to, their roles there and each membership's status.

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.

Responses

200 OK

application/json

{
    "id": "string",
    "memberships": [
        {
            "membership_id": "string",
            "organization": {
                "display_name": "string",
                "id": "string",
                "slug": "string"
            },
            "roles": [
                "string"
            ],
            "status": "string"
        }
    ],
    "profile": {
        "display_name": "string",
        "email": "string",
        "email_verified": true
    }
}

Get the organization¶

GET /v1/orgs/{org_id}

The organization's name, short name and state, and the caller's roles in 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

Responses

200 OK

application/jsonapplication/json

{
    "closure": {
        "billing_cutoff_at": "2022-04-13T15:42:05.901Z",
        "by_operator": true,
        "cancelled_at": "2022-04-13T15:42:05.901Z",
        "completed_at": "2022-04-13T15:42:05.901Z",
        "export": {
            "operation_id": "string",
            "ready_at": "2022-04-13T15:42:05.901Z",
            "requested_at": "2022-04-13T15:42:05.901Z"
        },
        "held": true,
        "records_kept_until": "2022-04-13T15:42:05.901Z",
        "requested_at": "2022-04-13T15:42:05.901Z",
        "retention_until": "2022-04-13T15:42:05.901Z",
        "usage_final_at": "2022-04-13T15:42:05.901Z"
    },
    "desired_lifecycle_state": "string",
    "display_name": "string",
    "id": "string",
    "lifecycle_state": "string",
    "slug": "string",
    "your_roles": [
        "string"
    ]
}

422 Unprocessable Entity

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

Get a location's catalog¶

GET /v1/orgs/{org_id}/catalog

What can be created in one location the organization may use: sizes, images, volume types and other offerings, each with whether it is available now.

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.
`location`	query	string		No
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "location": "string",
    "offerings": [
        {
            "attributes": {},
            "availability": "string",
            "display_name": "string",
            "kind": "string",
            "slug": "string"
        }
    ]
}

422 Unprocessable Entity

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

Get the organization's closure report¶

GET /v1/orgs/{org_id}/closure-report

What closing the organization would remove, per project and location, with how long it is kept before anything is destroyed.

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

{
    "projects": [
        {
            "display_name": "string",
            "placements": [
                {
                    "counts": {},
                    "empty": true,
                    "externally_visible": [
                        {
                            "display_name": "string",
                            "id": "string",
                            "type": "string",
                            "visibility": "string"
                        }
                    ],
                    "location": "string",
                    "placement_id": "string"
                }
            ],
            "project_id": "string",
            "slug": "string"
        }
    ],
    "records_retention_s": 0,
    "retention_s": 0
}

422 Unprocessable Entity

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

Download the organization's data export¶

GET /v1/orgs/{org_id}/data-export

The export an owner asked for while the organization is closing, once it is ready: the organization's records up to the time it was asked for, as JSON lines.

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/x-ndjsonapplication/json

"string"

422 Unprocessable Entity

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

Request the organization's data export¶

POST /v1/orgs/{org_id}/data-export

While the organization is closing, until its records are purged, an owner can ask for an export of its records: projects and locations, members and roles, usage, statements and the audit log. Accepted at once: follow the returned operation; the organization's closure says when the export is ready to download.

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

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

List locations¶

GET /v1/orgs/{org_id}/locations

The locations the organization may use, and whether each is taking new resources now.

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": [
        {
            "display_name": "string",
            "id": "string",
            "jurisdiction": "string",
            "maintenance_until": "2022-04-13T15:42:05.901Z",
            "slug": "string",
            "status": "string"
        }
    ]
}

422 Unprocessable Entity

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

Get my e-mail notices¶

GET /v1/orgs/{org_id}/notification-preferences

Which e-mail notices the caller receives from this organization.

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

{
    "email_enabled": true,
    "items": [
        {
            "description": "string",
            "enabled": true,
            "kind": "string"
        }
    ]
}

422 Unprocessable Entity

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

Set an e-mail notice¶

PUT /v1/orgs/{org_id}/notification-preferences/{kind}

Turns one kind of e-mail notice on or off for the caller.

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.
`kind`	path	string		No
`org_id`	path	string		No

Request body

application/json200 OK

{
    "enabled": true
}

Responses

application/jsonapplication/json

{
    "email_enabled": true,
    "items": [
        {
            "description": "string",
            "enabled": true,
            "kind": "string"
        }
    ]
}

422 Unprocessable Entity

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

Get the organization's settings¶

GET /v1/orgs/{org_id}/settings

The organization's settings, such as whether members may create projects and the second-factor rule, with their version for If-Match.

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

{
    "audit": {
        "export_enabled": true,
        "lookback_days": 0,
        "max_lookback_days": 0,
        "min_lookback_days": 0,
        "note": "string",
        "version": "string"
    },
    "descriptions": {},
    "invitation_domains": [
        "string"
    ],
    "members_create_projects": true,
    "mfa_grace_until": "2022-04-13T15:42:05.901Z",
    "mfa_required": true,
    "owner_only": [
        "string"
    ],
    "second_factor": {
        "always_for_roles": [
            "string"
        ],
        "platform_requires": true
    },
    "updated_at": "2022-04-13T15:42:05.901Z",
    "verified": true,
    "version": "string",
    "viewers_read_audit": true
}

422 Unprocessable Entity

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

Change the organization's settings¶

PATCH /v1/orgs/{org_id}/settings

Changes the settings sent and leaves the rest. Send the current version in If-Match; the security settings are the owners' alone.

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.
`if-match`	header	string		Yes
`org_id`	path	string		No

Request body

application/json200 OK

{
    "audit_export_enabled": true,
    "audit_lookback_days": 0,
    "audit_version": 0,
    "invitation_domains": [
        "string"
    ],
    "members_create_projects": true,
    "mfa_grace_days": 0,
    "mfa_required": true,
    "viewers_read_audit": true
}

Responses

application/jsonapplication/json

{
    "audit": {
        "export_enabled": true,
        "lookback_days": 0,
        "max_lookback_days": 0,
        "min_lookback_days": 0,
        "note": "string",
        "version": "string"
    },
    "descriptions": {},
    "invitation_domains": [
        "string"
    ],
    "members_create_projects": true,
    "mfa_grace_until": "2022-04-13T15:42:05.901Z",
    "mfa_required": true,
    "owner_only": [
        "string"
    ],
    "updated_at": "2022-04-13T15:42:05.901Z",
    "verified": true,
    "version": "string",
    "viewers_read_audit": true
}

422 Unprocessable Entity

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

Cancel the organization's closure¶

POST /v1/orgs/{org_id}:cancel-closure

Stops a closure that has not started destroying resources. 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

Responses

202 Accepted

application/jsonapplication/json

{
    "invitations_revoked": 0,
    "operations": [
        "string"
    ],
    "projects": [
        "string"
    ]
}

422 Unprocessable Entity

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

Close the organization¶

POST /v1/orgs/{org_id}:close

Starts closing the organization: every project is suspended and deleted after the retention period, unless the closure is cancelled. Owners only, with 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

Request body

application/json202 Accepted

{
    "confirmed_report": {}
}

Responses

application/jsonapplication/json

{
    "invitations_revoked": 0,
    "operations": [
        "string"
    ],
    "projects": [
        "string"
    ]
}

422 Unprocessable Entity

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

Schemas¶

Accepted¶

Name	Type	Description
`operation`	OperationLink

AuditSettings¶

Name	Type	Description
`export_enabled`	boolean
`lookback_days`	integer	How many days of it members read and export.
`max_lookback_days`	integer	The most the organization's tier allows.
`min_lookback_days`	integer
`note`	string
`version`	string	Send as `audit_version` when changing these.

Catalog¶

Name	Type	Description
`location`	string	The location (`loc_…`).
`offerings`	Array<Offering>

CloseBody¶

Name	Type	Description
`confirmed_report`

Closure¶

Name	Type	Description
`billing_cutoff_at`	string(date-time) \| null	Usage up to here is billed.
`by_operator`	boolean	Whether the provider closed it rather than an owner.
`cancelled_at`	string(date-time) \| null
`completed_at`	string(date-time) \| null
`export`	ClosureExport	The owners' data export while the organization is closing, if asked for.
`held`	boolean	Whether the provider holds the closure for now.
`records_kept_until`	string(date-time) \| null	Until when the audit log and usage are kept after closing.
`requested_at`	string(date-time) \| null
`retention_until`	string(date-time) \| null	Until when the closure can be cancelled.
`usage_final_at`	string(date-time) \| null

ClosureAccepted¶

Name	Type	Description
`invitations_revoked`	integer \| null	On closing: how many pending invitations were revoked.
`operations`	Array<string>	One operation per project (`op_…`), to follow.
`projects`	Array<string>	The projects it applies to (`prj_…`).

ClosureExport¶

Name	Type	Description
`operation_id`	string	The operation that prepares it (`op_…`).
`ready_at`	string(date-time) \| null	When it became ready to download.
`requested_at`	string(date-time)	When it was asked for: it holds records up to then.

ClosureProject¶

Name	Type	Description
`display_name`	string
`placements`	Array<PlacementReportView>
`project_id`	string
`slug`	string

ClosureReport¶

Name	Type	Description
`projects`	Array<ClosureProject>
`records_retention_s`	integer	How long, in seconds, the audit log and usage are kept after closing.
`retention_s`	integer	How long, in seconds, the data is kept first.

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

Location¶

Name	Type	Description
`display_name`	string
`id`	string	The location (`loc_…`).
`jurisdiction`	string
`maintenance_until`	string(date-time)	In maintenance only: when it is expected to end, if known.
`slug`	string
`status`	string	`available`, `closed_to_new_projects`, `maintenance`, `closing`, `unavailable` or `closed`.

LocationList¶

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

Me¶

Name	Type	Description
`id`	string	The caller (`usr_…`).
`memberships`	Array<OwnMembership>
`profile`	Profile

MembershipOrganization¶

Name	Type	Description
`display_name`	string
`id`	string	The organization (`org_…`).
`slug`	string

NoticePreference¶

Name	Type	Description
`description`	string
`enabled`	boolean
`kind`	string	Such as `maintenance_started`.

NoticePreferences¶

Name	Type	Description
`email_enabled`	boolean	Whether this installation sends e-mail at all.
`items`	Array<NoticePreference>

Offering¶

Name	Type	Description
`attributes`		What the offering is, by kind.
`availability`	string	Whether it can be created now, such as `available`.
`display_name`	string
`kind`	string	Such as `compute`, `image`, `volume_type` or `public_network`.
`slug`	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`.

Organization¶

Name	Type	Description
`closure`	Closure	The latest closure, if it was ever closed.
`desired_lifecycle_state`	string	`deleted` while it closes.
`display_name`	string
`id`	string
`lifecycle_state`	string
`slug`	string
`your_roles`	Array<string>

OrganizationSettings¶

Name	Type	Description
`audit`	AuditSettings
`descriptions`		What each setting does, by its name.
`invitation_domains`	Array<string>	Empty: invitations go to any domain.
`members_create_projects`	boolean
`mfa_grace_until`	string(date-time) \| null	Until when members without a second factor may still sign in.
`mfa_required`	boolean	Every member signs in with a second factor.
`owner_only`	Array<string>	The settings only an owner changes.
`updated_at`	string(date-time) \| null
`verified`	boolean
`version`	string	For `If-Match` when changing them.
`viewers_read_audit`	boolean

OrganizationSettingsView¶

Name	Type	Description
`audit`	AuditSettings
`descriptions`		What each setting does, by its name.
`invitation_domains`	Array<string>	Empty: invitations go to any domain.
`members_create_projects`	boolean
`mfa_grace_until`	string(date-time) \| null	Until when members without a second factor may still sign in.
`mfa_required`	boolean	Every member signs in with a second factor.
`owner_only`	Array<string>	The settings only an owner changes.
`second_factor`	SecondFactorRule
`updated_at`	string(date-time) \| null
`verified`	boolean
`version`	string	For `If-Match` when changing them.
`viewers_read_audit`	boolean

OwnMembership¶

Name	Type	Description
`membership_id`	string	The membership (`mem_…`).
`organization`	MembershipOrganization
`roles`	Array<string>
`status`	string	`active` or `suspended`.

PlacementReportView¶

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

PreferenceBody¶

Name	Type	Description
`enabled`	boolean

Profile¶

Name	Type	Description
`display_name`	string \| null
`email`	string \| null
`email_verified`	boolean

SecondFactorRule¶

Name	Type	Description
`always_for_roles`	Array<string>	The roles that always sign in with one.
`platform_requires`	boolean	Whether the provider requires it of everyone.

SettingsBody¶

Name	Type	Description
`audit_export_enabled`	boolean \| null
`audit_lookback_days`	integer \| null
`audit_version`	integer \| null
`invitation_domains`	Array<string>
`members_create_projects`	boolean \| null
`mfa_grace_days`	integer \| null
`mfa_required`	boolean \| null
`viewers_read_audit`	boolean \| null

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