File openapi.yaml of Package linode-cli
openapi: 3.0.1
info:
version: 4.139.0
title: Linode API
description: |
## Introduction
The Linode API provides the ability to programmatically manage the full
range of Linode products and services.
This reference is designed to assist application developers and system
administrators. Each endpoint includes descriptions, request syntax, and
examples using standard HTTP requests. Response data is returned in JSON
format.
This document was generated from our OpenAPI Specification. See the
<a target="_top" href="https://www.openapis.org">OpenAPI website</a> for more information.
<a target="_top" href="/docs/api/openapi.yaml">Download the Linode OpenAPI Specification</a>.
## Changelog
<a target="_top" href="https://developers.linode.com/changelog">View our Changelog</a> to see release
notes on all changes made to our API.
## Access and Authentication
Some endpoints are publicly accessible without requiring authentication.
All endpoints affecting your Account, however, require either a Personal
Access Token or OAuth authentication (when using third-party
applications).
### Personal Access Token
The easiest way to access the API is with a Personal Access Token (PAT)
generated from the
<a target="_top" href="https://cloud.linode.com/profile/tokens">Linode Cloud Manager</a> or
the [Create Personal Access Token](/docs/api/profile/#personal-access-token-create) endpoint.
All scopes for the OAuth security model ([defined below](/docs/api/profile/#oauth)) apply to this
security model as well.
#### Authentication
| Security Scheme Type: | HTTP |
|-----------------------|------|
| **HTTP Authorization Scheme** | bearer |
### OAuth
If you only need to access the Linode API for personal use,
we recommend that you create a [personal access token](/docs/api/#personal-access-token).
If you're designing an application that can authenticate with an arbitrary Linode user, then
you should use the OAuth 2.0 workflows presented in this section.
For a more detailed example of an OAuth 2.0 implementation, see our guide on [How to Create an OAuth App with the Linode Python API Library](/docs/platform/api/how-to-create-an-oauth-app-with-the-linode-python-api-library/#oauth-2-authentication-exchange).
Before you implement OAuth in your application, you first need to create an OAuth client. You can do this [with the Linode API](/docs/api/account/#oauth-client-create) or [via the Cloud Manager](https://cloud.linode.com/profile/clients):
- When creating the client, you'll supply a `label` and a `redirect_uri` (referred to as the Callback URL in the Cloud Manager).
- The response from this endpoint will give you a `client_id` and a `secret`.
- Clients can be public or private, and are private by default. You can choose to make the client public when it is created.
- A private client is used with applications which can securely store the client secret (that is, the secret returned to you when you first created the client). For example, an application running on a secured server that only the developer has access to would use a private OAuth client. This is also called a confidential client in some OAuth documentation.
- A public client is used with applications where the client secret is not guaranteed to be secure. For example, a native app running on a user's computer may not be able to keep the client secret safe, as a user could potentially inspect the source of the application. So, native apps or apps that run in a user's browser should use a public client.
- Public and private clients follow different workflows, as described below.
#### OAuth Workflow
The OAuth workflow is a series of exchanges between your third-party app and Linode. The workflow is used
to authenticate a user before an application can start making API calls on the user's behalf.
Notes:
- With respect to the diagram in [section 1.2 of RFC 6749](https://tools.ietf.org/html/rfc6749#section-1.2), login.linode.com (referred to in this section as the *login server*)
is the Resource Owner and the Authorization Server; api.linode.com (referred to here as the *api server*) is the Resource Server.
- The OAuth spec refers to the private and public workflows listed below as the [authorization code flow](https://tools.ietf.org/html/rfc6749#section-1.3.1) and [implicit flow](https://tools.ietf.org/html/rfc6749#section-1.3.2).
| PRIVATE WORKFLOW | PUBLIC WORKFLOW |
|------------------|------------------|
| 1. The user visits the application's website and is directed to login with Linode. | 1. The user visits the application's website and is directed to login with Linode. |
| 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. | 2. Your application then redirects the user to Linode's [login server](https://login.linode.com) with the client application's `client_id` and requested OAuth `scope`, which should appear in the URL of the login page. |
| 3. The user logs into the login server with their username and password. | 3. The user logs into the login server with their username and password. |
| 4. The login server redirects the user to the specificed redirect URL with a temporary authorization `code` (exchange code) in the URL. | 4. The login server redirects the user back to your application with an OAuth `access_token` embedded in the redirect URL's hash. This is temporary and expires in two hours. No `refresh_token` is issued. Therefore, once the `access_token` expires, a new one will need to be issued by having the user log in again. |
| 5. The application issues a POST request (*see additional details below*) to the login server with the exchange code, `client_id`, and the client application's `client_secret`. | |
| 6. The login server responds to the client application with a new OAuth `access_token` and `refresh_token`. The `access_token` is set to expire in two hours. | |
| 7. The `refresh_token` can be used by contacting the login server with the `client_id`, `client_secret`, `grant_type`, and `refresh_token` to get a new OAuth `access_token` and `refresh_token`. The new `access_token` is good for another two hours, and the new `refresh_token` can be used to extend the session again by this same method (*see additional details below*). | |
#### OAuth Private Workflow - Additional Details
The following information expands on steps 5 through 7 of the private workflow:
Once the user has logged into Linode and you have received an exchange code,
you will need to trade that exchange code for an `access_token` and `refresh_token`. You
do this by making an HTTP POST request to the following address:
```
https://login.linode.com/oauth/token
```
Make this request as `application/x-www-form-urlencoded` or as
`multipart/form-data` and include the following parameters in the POST body:
| PARAMETER | DESCRIPTION |
|-----------|-------------|
| client_id | Your app's client ID. |
| client_secret | Your app's client secret. |
| code | The code you just received from the redirect. |
You'll get a response like this:
```json
{
"scope": "linodes:read_write",
"access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c",
"refresh_token": "f2ec9712e616fdb5a2a21aa0e88cfadea7502ebc62cf5bd758dbcd65e1803bad",
"token_type": "bearer",
"expires_in": 7200
}
```
Included in the response is an `access_token`. With this token, you can proceed to make
authenticated HTTP requests to the API by adding this header to each request:
```
Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c
```
This `access_token` is set to expire in two hours. To refresh access prior to expiration, make another request to the same URL with the following parameters in the POST body:
| PARAMETER | DESCRIPTION |
|-----------|-------------|
| grant_type | The grant type you're using. Use "refresh_token" when refreshing access. |
| client_id | Your app's client ID. |
| client_secret | Your app's client secret. |
| refresh_token | The `refresh_token` received from the previous response. |
You'll get another response with an updated `access_token` and `refresh_token`, which can then be used to refresh access again.
#### OAuth Reference
| Security Scheme Type | OAuth 2.0 |
|-----------------------|--------|
| **Authorization URL** | https://login.linode.com/oauth/authorize |
| **Token URL** | https://login.linode.com/oauth/token |
| **Scopes** | <ul><li>`account:read_only` - Allows access to GET information about your Account.</li><li>`account:read_write` - Allows access to all endpoints related to your Account.</li><li>`databases:read_only` - Allows access to GET Managed Databases on your Account.</li><li>`databases:read_write` - Allows access to all endpoints related to your Managed Databases.</li><li>`domains:read_only` - Allows access to GET Domains on your Account.</li><li>`domains:read_write` - Allows access to all Domain endpoints.</li><li>`events:read_only` - Allows access to GET your Events.</li><li>`events:read_write` - Allows access to all endpoints related to your Events.</li><li>`firewall:read_only` - Allows access to GET information about your Firewalls.</li><li>`firewall:read_write` - Allows access to all Firewall endpoints.</li><li>`images:read_only` - Allows access to GET your Images.</li><li>`images:read_write` - Allows access to all endpoints related to your Images.</li><li>`ips:read_only` - Allows access to GET your ips.</li><li>`ips:read_write` - Allows access to all endpoints related to your ips.</li><li>`linodes:read_only` - Allows access to GET Linodes on your Account.</li><li>`linodes:read_write` - Allow access to all endpoints related to your Linodes.</li><li>`lke:read_only` - Allows access to GET LKE Clusters on your Account.</li><li>`lke:read_write` - Allows access to all endpoints related to LKE Clusters on your Account.</li><li>`longview:read_only` - Allows access to GET your Longview Clients.</li><li>`longview:read_write` - Allows access to all endpoints related to your Longview Clients.</li><li>`maintenance:read_only` - Allows access to GET information about Maintenance on your account.</li><li>`nodebalancers:read_only` - Allows access to GET NodeBalancers on your Account.</li><li>`nodebalancers:read_write` - Allows access to all NodeBalancer endpoints.</li><li>`object_storage:read_only` - Allows access to GET information related to your Object Storage.</li><li>`object_storage:read_write` - Allows access to all Object Storage endpoints.</li><li>`stackscripts:read_only` - Allows access to GET your StackScripts.</li><li>`stackscripts:read_write` - Allows access to all endpoints related to your StackScripts.</li><li>`volumes:read_only` - Allows access to GET your Volumes.</li><li>`volumes:read_write` - Allows access to all endpoints related to your Volumes.</li></ul><br/>|
## Requests
Requests must be made over HTTPS to ensure transactions are encrypted. The
following Request methods are supported:
| METHOD | USAGE |
|--------|-------|
| GET | Retrieves data about collections and individual resources. |
| POST | For collections, creates a new resource of that type. Also used to perform actions on action endpoints. |
| PUT | Updates an existing resource. |
| DELETE | Deletes a resource. This is a destructive action. |
## Responses
Actions will return one following HTTP response status codes:
| STATUS | DESCRIPTION |
|---------|-------------|
| 200 OK | The request was successful. |
| 202 Accepted | The request was successful, but processing has not been completed. The response body includes a "warnings" array containing the details of incomplete processes. |
| 204 No Content | The server successfully fulfilled the request and there is no additional content to send. |
| 299 Deprecated | The request was successful, but involved a deprecated endpoint. The response body includes a "warnings" array containing warning messages. |
| 400 Bad Request | You submitted an invalid request (missing parameters, etc.). |
| 401 Unauthorized | You failed to authenticate for this resource. |
| 403 Forbidden | You are authenticated, but don't have permission to do this. |
| 404 Not Found | The resource you're requesting does not exist. |
| 429 Too Many Requests | You've hit a rate limit. |
| 500 Internal Server Error | Please [open a Support Ticket](/docs/api/support/#support-ticket-open). |
## Errors
Success is indicated via <a href="https://en.wikipedia.org/wiki/List_of_HTTP_status_codes" target="_top">Standard HTTP status codes</a>.
`2xx` codes indicate success, `4xx` codes indicate a request error, and
`5xx` errors indicate a server error. A
request error might be an invalid input, a required parameter being omitted,
or a malformed request. A server error means something went wrong processing
your request. If this occurs, please
[open a Support Ticket](/docs/api/support/#support-ticket-open)
and let us know. Though errors are logged and we work quickly to resolve issues,
opening a ticket and providing us with reproducable steps and data is always helpful.
The `errors` field is an array of the things that went wrong with your request.
We will try to include as many of the problems in the response as possible,
but it's conceivable that fixing these errors and resubmitting may result in
new errors coming back once we are able to get further along in the process
of handling your request.
Within each error object, the `field` parameter will be included if the error
pertains to a specific field in the JSON you've submitted. This will be
omitted if there is no relevant field. The `reason` is a human-readable
explanation of the error, and will always be included.
## Pagination
Resource lists are always paginated. The response will look similar to this:
```json
{
"data": [ ... ],
"page": 1,
"pages": 3,
"results": 300
}
```
* Pages start at 1. You may retrieve a specific page of results by adding
`?page=x` to your URL (for example, `?page=4`). If the value of `page`
exceeds `2^64/page_size`, the last possible page will be returned.
* Page sizes default to 100,
and can be set to return between 25 and 500. Page size can be set using
`?page_size=x`.
## Filtering and Sorting
Collections are searchable by fields they include, marked in the spec as
`x-linode-filterable: true`. Filters are passed
in the `X-Filter` header and are formatted as JSON objects. Here is a request
call for Linode Types in our "standard" class:
```Shell
curl "https://api.linode.com/v4/linode/types" \
-H '
X-Filter: {
"class": "standard"
}'
```
The filter object's keys are the keys of the object you're filtering,
and the values are accepted values. You can add multiple filters by
including more than one key. For example, filtering for "standard" Linode
Types that offer one vcpu:
```Shell
curl "https://api.linode.com/v4/linode/types" \
-H '
X-Filter: {
"class": "standard",
"vcpus": 1
}'
```
In the above example, both filters are combined with an "and" operation.
However, if you wanted either Types with one vcpu or Types in our "standard"
class, you can add an operator:
```Shell
curl "https://api.linode.com/v4/linode/types" \
-H '
X-Filter: {
"+or": [
{ "vcpus": 1 },
{ "class": "standard" }
]
}'
```
Each filter in the `+or` array is its own filter object, and all conditions
in it are combined with an "and" operation as they were in the previous example.
Other operators are also available. Operators are keys of a Filter JSON
object. Their value must be of the appropriate type, and they are evaluated
as described below:
| OPERATOR | TYPE | DESCRIPTION |
|----------|--------|-----------------------------------|
| +and | array | All conditions must be true. |
| +or | array | One condition must be true. |
| +gt | number | Value must be greater than number. |
| +gte | number | Value must be greater than or equal to number. |
| +lt | number | Value must be less than number. |
| +lte | number | Value must be less than or equal to number. |
| +contains | string | Given string must be in the value. |
| +neq | string | Does not equal the value. |
| +order_by | string | Attribute to order the results by - must be filterable. |
| +order | string | Either "asc" or "desc". Defaults to "asc". Requires `+order_by`. |
For example, filtering for [Linode Types](/docs/api/linode-types/)
that offer memory equal to or higher than 61440:
```Shell
curl "https://api.linode.com/v4/linode/types" \
-H '
X-Filter: {
"memory": {
"+gte": 61440
}
}'
```
You can combine and nest operators to construct arbitrarily-complex queries.
For example, give me all [Linode Types](/docs/api/linode-types/)
which are either `standard` or `highmem` class, or
have between 12 and 20 vcpus:
```Shell
curl "https://api.linode.com/v4/linode/types" \
-H '
X-Filter: {
"+or": [
{
"+or": [
{
"class": "standard"
},
{
"class": "highmem"
}
]
},
{
"+and": [
{
"vcpus": {
"+gte": 12
}
},
{
"vcpus": {
"+lte": 20
}
}
]
}
]
}'
```
## Time Values
All times returned by the API are in UTC, regardless of the timezone configured within your user's profile (see `timezone` property within [Profile View](/docs/api/profile/#profile-view__responses)).
## Rate Limiting
Rate limits on API requests help maintain the health and stability of the Linode API. Accordingly, every endpoint of the Linode API applies a rate limit on a per user basis as determined by OAuth token for authenticated requests or IP address for public endpoints.
Each rate limit consists of a total number of requests and a time window. For example, if an endpoint has a rate limit of 800 requests per minute, then up to 800 requests over a one minute window are permitted. Subsequent requests to an endpoint after hitting a rate limit return a 429 error. You can successfully remake requests to that endpoint after the rate limit window resets.
### Linode APIv4 Rate Limits
With the Linode API, you can generally make up to 1,600 general API requests every two minutes. Additionally, all endpoints have a rate limit of 800 requests per minute unless otherwise specified below.
**Note:** There may be rate limiting applied at other levels outside of the API, for example, at the load balancer.
Creating Linodes has a dedicated rate limit of 10 requests per 30 seconds. That endpoint is:
* [Linode Create](/docs/api/linode-instances/#linode-create)
`/stats` endpoints have their own dedicated rate limits of 100 requests per minute. These endpoints are:
* [View Linode Statistics](/docs/api/linode-instances/#linode-statistics-view)
* [View Linode Statistics (year/month)](/docs/api/linode-instances/#statistics-yearmonth-view)
* [View NodeBalancer Statistics](/docs/api/nodebalancers/#nodebalancer-statistics-view)
* [List Managed Stats](/docs/api/managed/#managed-stats-list)
Object Storage endpoints have a dedicated rate limit of 750 requests per second. The Object Storage endpoints are:
* [Object Storage Endpoints](/docs/api/object-storage/)
Opening Support Tickets has a dedicated rate limit of 2 requests per minute. That endpoint is:
* [Open Support Ticket](/docs/api/support/#support-ticket-open)
Accepting Service Transfers has a dedicated rate limit of 2 requests per minute. That endpoint is:
* [Service Transfer Accept](/docs/api/account/#service-transfer-accept)
### Rate Limit HTTP Response Headers
The Linode API includes the following HTTP response headers which are designed to help you avoid hitting rate limits that might disrupt your applications:
* **X-RateLimit-Limit**: The maximum number of permitted requests during the rate limit window for this endpoint.
* **X-RateLimit-Remaining**: The remaining number of permitted requests in the current rate limit window.
* **X-RateLimit-Reset**: The time when the current rate limit window rests in UTC epoch seconds.
* **Retry-After**: The remaining time in seconds until the current rate limit window resets.
There are many ways to access header information for your requests, depending on how you are accessing the Linode API. For example, to view HTTP response headers when making requests with `curl`, use the `-i` or `--include` option as follows:
```Shell
curl -i https://api.linode.com/v4/regions
```
## CLI (Command Line Interface)
The <a href="https://github.com/linode/linode-cli" target="_top">Linode CLI</a> allows you to easily
work with the API using intuitive and simple syntax. It requires a
[Personal Access Token](/docs/api/#personal-access-token)
for authentication, and gives you access to all of the features and functionality
of the Linode API that are documented here with CLI examples.
Endpoints that do not have CLI examples are currently unavailable through the CLI, but
can be accessed via other methods such as Shell commands and other third-party applications.
contact:
name: Linode
url: https://linode.com
email: support@linode.com
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
paths:
/account:
x-linode-cli-command: account
get:
x-linode-grant: read_only
tags:
- Account
summary: Account View
description: >
Returns the contact and billing information related to
your Account.
operationId: getAccount
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a single Account object.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account
- lang: CLI
source: >
linode-cli account view
put:
x-linode-grant: read_write
tags:
- Account
summary: Account Update
description: >
Updates contact and billing information
related to your Account.
operationId: updateAccount
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: |
Update contact and billing information.
Account properties that are excluded from a request remain unchanged.
When updating an Account's `country` to "US", an error is returned if the Account's `zip` is not a valid US zip code.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
responses:
'200':
description: The updated Account.
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"address_1": "123 Main St.",
"address_2": "Suite 101",
"city": "Philadelphia",
"company": "My Company, LLC",
"country": "US",
"email": "jsmith@mycompany.com",
"first_name": "John",
"last_name": "Smith",
"phone": "555-555-1212",
"state": "PA",
"tax_id": "ATU99999999",
"zip": "19102"
}' \
https://api.linode.com/v4/account
- lang: CLI
source: >
linode-cli account update \
--address_1 "123 Main St." \
--address_2 "Suite 101" \
--city Philadelphia \
--company My Company \ LLC \
--country US \
--email jsmith@mycompany.com \
--first_name John \
--last_name Smith \
--phone 555-555-1212 \
--state PA \
--tax_id ATU99999999 \
--zip 19102
/account/cancel:
x-linode-cli-command: account
post:
x-linode-grant: read_write
tags:
- Account
summary: Account Cancel
description: >
Cancels an active Linode account. This action will cause
Linode to attempt to charge the credit card on file for the remaining
balance. An error will occur if Linode fails to charge the credit card
on file. Restricted users will not be able to cancel an account.
operationId: cancelAccount
x-linode-cli-action: cancel
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
Supply a comment stating the reason that you are cancelling your account.
required: true
content:
application/json:
schema:
properties:
comments:
type: string
description: >
Any reason for cancelling the account, and any other comments
you might have about your Linode service.
example: "I'm consolidating multiple accounts into one."
responses:
'200':
description: Account cancelled
content:
application/json:
schema:
type: object
properties:
survey_link:
type: string
description: A link to Linode's exit survey.
example: {'survey_link': https://alinktothesurvey.com'}
'409':
description: Could not charge the credit card on file
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
reason:
type: string
description: >
A string explaining that the account could not be cancelled
because there is an outstanding balance on the account
that must be paid first.
example: >
We were unable to charge your credit
card for services rendered. We cannot cancel
this account until the balance has been paid.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"comments": "I am consolidating my accounts."
}' \
https://api.linode.com/v4/account/cancel
- lang: CLI
source: >
linode-cli account cancel \
--comments "I'm consolidating my accounts"
/account/credit-card:
x-linode-cli-command: account
post:
deprecated: true
x-linode-cli-skip: true
x-linode-grant: read_write
tags:
- Account
summary: Credit Card Add/Edit
description: |
**DEPRECATED**. Please use Payment Method Add ([POST /account/payment-methods](/docs/api/account/#payment-method-add)).
Adds a credit card Payment Method to your account and sets it as the default method.
operationId: createCreditCard
x-linode-cli-action: update-card
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Update the credit card information associated with your Account.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreditCard'
responses:
'200':
description: Credit Card updated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"card_number": "4111111111111111",
"expiry_month": 11,
"expiry_year": 2020,
"cvv": "111"
}' \
https://api.linode.com/v4/account/credit-card
- lang: CLI
source: >
linode-cli account update-card \
--card_number 4111111111111111 \
--expiry_month 11 \
--expiry_year 2025 \
--cvv 111
/account/entity-transfers:
get:
deprecated: true
x-linode-grant: unrestricted only
x-linode-cli-skip: true
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Entity Transfers List
description: >
**DEPRECATED**. Please use [Service Transfers List](/docs/api/account/#service-transfers-list).
operationId: getEntityTransfers
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
Returns a paginated list of Entity Transfer objects containing the details of all transfers that have been
created and accepted by this account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- properties:
data:
type: array
items:
$ref: '#/components/schemas/EntityTransfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/entity-transfers
post:
deprecated: true
x-linode-grant: unrestricted only
x-linode-cli-skip: true
tags:
- Account
summary: Entity Transfer Create
description: >
**DEPRECATED**. Please use [Service Transfer Create](/docs/api/account/#service-transfer-create).
operationId: createEntityTransfer
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The entities to include in this transfer request.
content:
application/json:
schema:
required:
- entities
type: object
properties:
entities:
$ref: '#/components/schemas/EntityTransfer/properties/entities'
responses:
'200':
description: >
Returns an Entity Transfer object for the request.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityTransfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"entities": {
"linodes": [
111,
222
]
}
}' \
https://api.linode.com/v4/account/entity-transfers
/account/entity-transfers/{token}:
parameters:
- name: token
in: path
description: The UUID of the Entity Transfer.
required: true
schema:
type: string
format: uuid
get:
deprecated: true
x-linode-grant: unrestricted only
x-linode-cli-skip: true
tags:
- Account
summary: Entity Transfer View
description: >
**DEPRECATED**. Please use [Service Transfer View](/docs/api/account/#service-transfer-view).
operationId: getEntityTransfer
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
Returns an Entity Transfer object containing the details of the transfer for the specified token.
content:
application/json:
schema:
$ref: '#/components/schemas/EntityTransfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/entity-transfers/123E4567-E89B-12D3-A456-426614174000
delete:
deprecated: true
x-linode-grant: unrestricted only
x-linode-cli-skip: true
tags:
- Account
summary: Entity Transfer Cancel
description: >
**DEPRECATED**. Please use [Service Transfer Cancel](/docs/api/account/#service-transfer-cancel).
operationId: deleteEntityTransfer
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: >
Entity Transfer cancelled.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/account/entity-transfers/123E4567-E89B-12D3-A456-426614174000
/account/entity-transfers/{token}/accept:
parameters:
- name: token
in: path
description: The UUID of the Entity Transfer.
required: true
schema:
type: string
format: uuid
post:
deprecated: true
x-linode-grant: unrestricted only
x-linode-cli-skip: true
tags:
- Account
summary: Entity Transfer Accept
description: >
**DEPRECATED**. Please use [Service Transfer Accept](/docs/api/account/#service-transfer-accept).
operationId: acceptEntityTransfer
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: >
Entity Transfer accepted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/entity-transfers/123E4567-E89B-12D3-A456-426614174000/accept
/account/events:
x-linode-cli-command: events
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Events List
description: >
Returns a collection of Event objects representing
actions taken on your Account from the last 90 days.
The Events returned depend on your grants.
operationId: getEvents
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- events:read_only
responses:
'200':
description: >
Returns a paginated lists of Event objects from
the last 90 days.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Event'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/events
- lang: CLI
source: >
linode-cli events list
/account/events/{eventId}:
x-linode-cli-command: events
parameters:
- name: eventId
in: path
description: The ID of the Event.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Account
summary: Event View
description: >
Returns a single Event object.
operationId: getEvent
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- events:read_only
responses:
'200':
description: An Event object
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/events/123
- lang: CLI
source: >
linode-cli events view 123
/account/events/{eventId}/read:
x-linode-cli-command: events
parameters:
- name: eventId
in: path
description: The ID of the Event to designate as read.
required: true
schema:
type: integer
post:
x-linode-grant: read_only
tags:
- Account
summary: Event Mark as Read
description: Marks a single Event as read.
operationId: eventRead
x-linode-cli-action: mark-read
security:
- personalAccessToken: []
- oauth:
- events:read_only
responses:
'200':
description: Event read.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/events/123/read
- lang: CLI
source: >
linode-cli events mark-read 123
/account/events/{eventId}/seen:
x-linode-cli-command: events
parameters:
- name: eventId
in: path
description: The ID of the Event to designate as seen.
required: true
schema:
type: integer
post:
x-linode-grant: read_write
tags:
- Account
summary: Event Mark as Seen
description: >
Marks all Events up to and including this Event by ID as seen.
operationId: eventSeen
x-linode-cli-action: mark-seen
security:
- personalAccessToken: []
- oauth:
- events:read_only
responses:
'200':
description: Events seen.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/events/123/seen
- lang: CLI
source: >
linode-cli events mark-seen 123
/account/invoices:
x-linode-cli-command: account
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Invoices List
description: >
Returns a paginated list of Invoices against your Account.
operationId: getInvoices
x-linode-cli-action: invoices-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of Invoice objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Invoice'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/invoices
- lang: CLI
source: >
linode-cli account invoices-list
/account/invoices/{invoiceId}:
x-linode-cli-command: account
parameters:
- name: invoiceId
in: path
description: The ID of the Invoice.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Account
summary: Invoice View
description: Returns a single Invoice object.
operationId: getInvoice
x-linode-cli-action: invoice-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: An Invoice object
content:
application/json:
schema:
$ref: '#/components/schemas/Invoice'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/invoices/123
- lang: CLI
source: >
linode-cli account invoice-view 123
/account/invoices/{invoiceId}/items:
x-linode-cli-command: account
parameters:
- name: invoiceId
in: path
description: The ID of the Invoice.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Invoice Items List
description: Returns a paginated list of Invoice items.
operationId: getInvoiceItems
x-linode-cli-action: invoice-items
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of InvoiceItem objects
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/InvoiceItem'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/invoices/123/items
- lang: CLI
source: >
linode-cli account invoice-items 123
/account/logins:
x-linode-cli-command: account
get:
tags:
- Account
summary: User Logins List All
description: >
Returns a collection of successful logins for all users on the account during the last
90 days. This command can only be accessed by the unrestricted users of an account.
operationId: getAccountLogins
x-linode-cli-action: logins-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
A collection of successful logins for all users on the account during the last
90 days.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Login'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/logins
- lang: CLI
source: >
linode-cli account logins-list
/account/logins/{loginId}:
parameters:
- name: loginId
in: path
description: The ID of the login object to access.
required: true
schema:
type: integer
x-linode-cli-command: account
get:
tags:
- Account
summary: Login View
description: >
Returns a Login object that displays information about a successful login.
The logins that can be viewed can be for any user on the account, and are not
limited to only the logins of the user that is accessing this API endpoint.
This command can only be accessed by the unrestricted users of the account.
operationId: getAccountLogin
x-linode-cli-action: login-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested login object.
content:
application/json:
schema:
$ref: '#/components/schemas/Login'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/logins/1234
- lang: CLI
source: >
linode-cli account login-view 1234
/account/maintenance:
x-linode-cli-command: account
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4beta
tags:
- Account
summary: Maintenance List
description: >
Returns a collection of Maintenance objects for any entity
a user has permissions to view.
Currently, Linodes are the only entities available for viewing.
**Beta**: This endpoint is in beta. Please make sure to prepend all requests with
`/v4beta` instead of `/v4`, and be aware that this endpoint may receive breaking
updates in the future. This notice will be removed when this endpoint is out of
beta.
operationId: getMaintenance
x-linode-cli-action: maintenance-list
security:
- personalAccessToken: []
- oauth:
- maintenance:read_only
responses:
'200':
description: Returns a paginated list of Maintenance objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Maintenance'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4beta/account/maintenance
- lang: CLI
source: >
linode-cli account maintenance-list
/account/notifications:
x-linode-cli-command: account
get:
x-linode-grant: read_only
tags:
- Account
summary: Notifications List
description: >
Returns a collection of Notification objects representing
important, often time-sensitive items related to your Account.
You cannot interact directly with Notifications, and a Notification will disappear
when the circumstances causing it have been resolved. For
example, if you have an important Ticket open, you must respond to the
Ticket to dismiss the Notification.
operationId: getNotifications
x-linode-cli-action: notifications-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of Notification objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Notification'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/notifications
- lang: CLI
source: >
linode-cli account notifications-list
/account/oauth-clients:
x-linode-cli-command: account
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: OAuth Clients List
description: >
Returns a paginated list of OAuth Clients registered to your Account. OAuth
Clients allow users to log into applications you write or host using their
Linode Account, and may allow them to grant some level of access to their
Linodes or other entities to your application.
operationId: getClients
x-linode-cli-action: clients-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of OAuth Clients.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/OAuthClient'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/oauth-clients
- lang: CLI
source: >
linode-cli account clients-list
post:
tags:
- Account
summary: OAuth Client Create
description: >
Creates an OAuth Client, which can be used to allow users
(using their Linode account) to log in to your own application, and optionally grant
your application some amount of access to their Linodes or other entities.
operationId: createClient
x-linode-cli-action: client-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the OAuth Client to create.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OAuthClient'
required:
- label
- redirect_uri
responses:
'200':
description: Client created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"redirect_uri": "https://example.org/oauth/callback",
"label": "Test_Client_1",
"public": false
}' \
https://api.linode.com/v4/account/oauth-clients
- lang: CLI
source: >
linode-cli account client-create \
--label Test_Client_1 \
--redirect_uri https://example.org/callback
/account/oauth-clients/{clientId}:
parameters:
- name: clientId
in: path
description: The OAuth Client ID to look up.
required: true
schema:
type: string
x-linode-cli-command: account
get:
tags:
- Account
summary: OAuth Client View
description: >
Returns information about a single OAuth client.
operationId: getClient
x-linode-cli-action: client-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Information about the requested client.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c
- lang: CLI
source: >
linode-cli account client-view \
edc6790ea9db4d224c5c
put:
tags:
- Account
summary: OAuth Client Update
description: >
Update information about an OAuth Client on your Account. This can be
especially useful to update the `redirect_uri` of your client in the event
that the callback url changed in your application.
operationId: updateClient
x-linode-cli-action: client-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClient'
responses:
'200':
description: Client updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"redirect_uri": "https://example.org/oauth/callback",
"label": "Test_Client_1"
}
}' \
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c
- lang: CLI
source: >
linode-cli account client-update \
edc6790ea9db4d224c5c \
--label Test_Client_1
delete:
tags:
- Account
summary: OAuth Client Delete
description: >
Deletes an OAuth Client registered with Linode. The Client ID and
Client secret will no longer be accepted by <a target="_top" href="https://login.linode.com">https://login.linode.com</a>,
and all tokens issued to this client will be invalidated (meaning that
if your application was using a token, it will no longer work).
operationId: deleteClient
x-linode-cli-action: client-delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Client deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c
- lang: CLI
source: >
linode-cli account client-delete \
edc6790ea9db4d224c5c
/account/oauth-clients/{clientId}/reset-secret:
x-linode-cli-command: account
parameters:
- name: clientId
in: path
description: The OAuth Client ID to look up.
required: true
schema:
type: string
post:
tags:
- Account
summary: OAuth Client Secret Reset
description: >
Resets the OAuth Client secret for a client you own, and returns the
OAuth Client with the plaintext secret. This secret is not supposed to
be publicly known or disclosed anywhere. This can be used to generate
a new secret in case the one you have has been leaked, or to get a new
secret if you lost the original. The old secret is expired immediately,
and logins to your client with the old secret will fail.
operationId: resetClientSecret
x-linode-cli-action: client-reset-secret
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Client secret reset successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c/reset-secret
- lang: CLI
source: >
linode-cli account client-reset-secret \
edc6790ea9db4d224c5c
/account/oauth-clients/{clientId}/thumbnail:
x-linode-cli-command: account
parameters:
- name: clientId
in: path
description: The OAuth Client ID to look up.
required: true
schema:
type: string
get:
tags:
- Account
summary: OAuth Client Thumbnail View
description: >
Returns the thumbnail for this OAuth Client. This is a
publicly-viewable endpoint, and can be accessed without authentication.
operationId: getClientThumbnail
x-linode-cli-skip: true
x-linode-cli-action: client-thumbnail
responses:
'200':
description: The client's thumbnail.
content:
image/png:
schema:
type: string
format: binary
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c/thumbnail > thumbnail.png
put:
tags:
- Account
summary: OAuth Client Thumbnail Update
description: >
Upload a thumbnail for a client you own. You must upload an image file
that will be returned when the thumbnail is retrieved. This image will
be publicly-viewable.
operationId: setClientThumbnail
x-linode-cli-skip: true
x-linode-cli-action: update-client-thumbnail
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The image to set as the thumbnail.
required: true
content:
image/png:
schema:
type: string
format: binary
responses:
'200':
description: Thumbnail updated successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: image/png" \
-H "Authorization: Bearer $TOKEN" \
-X PUT \
--data-binary "/path/to/image"
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c/thumbnail
/account/payment-methods:
x-linode-cli-command: payment-methods
get:
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
x-linode-grant: read_only
tags:
- Account
summary: Payment Methods List
description: |
Returns a paginated list of Payment Methods for this Account.
operationId: getPaymentMethods
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of Payment Method objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/payment-methods
- lang: CLI
source: >
linode-cli payment-methods list
post:
servers:
- url: https://api.linode.com/v4
x-linode-grant: read_write
tags:
- Account
summary: Payment Method Add
description: |
Adds a Payment Method to your Account with the option to set it as the default method.
* Adding a default Payment Method removes the default status from any other Payment Method.
* An Account can have up to 6 active Payment Methods.
* Up to 60 Payment Methods can be added each day.
* Prior to adding a Payment Method, ensure that your billing address information is up-to-date
with a valid `zip` by using the Account Update ([PUT /account](/docs/api/account/#account-update)) endpoint.
* A `payment_method_add` event is generated when a payment is successfully submitted.
operationId: createPaymentMethod
x-linode-cli-action: add
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The details of the Payment Method to add.
required: true
content:
application/json:
schema:
type: object
description: Payment Method Request Object.
required:
- type
- data
- is_default
properties:
type:
type: string
enum:
- credit_card
description: |
The type of Payment Method.
Alternative Payment Methods including Google Pay and PayPal can be added using Linode Cloud Manager. See our
guide on [Managing Billing in the Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/)
for details and instructions.
example: 'credit_card'
is_default:
$ref: '#/components/schemas/PaymentMethod/properties/is_default'
data:
$ref: '#/components/schemas/CreditCard'
responses:
'200':
description: Payment Method added.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "credit_card",
"is_default": true,
"data": {
"card_number": "4111111111111111",
"expiry_month": 11,
"expiry_year": 2020,
"cvv": "111"
}
}' \
https://api.linode.com/v4/account/payment-methods
- lang: CLI
source: >
linode-cli payment-methods add \
--type credit_card \
--is_default true \
--data.card_number 4111111111111111 \
--data.expiry_month 11 \
--data.expiry_year 2020 \
--data.cvv 111
/account/payment-methods/{paymentMethodId}:
x-linode-cli-command: payment-methods
parameters:
- name: paymentMethodId
in: path
description: The ID of the Payment Method to look up.
required: true
schema:
type: integer
get:
servers:
- url: https://api.linode.com/v4
x-linode-grant: read_only
tags:
- Account
summary: Payment Method View
description: |
View the details of the specified Payment Method.
operationId: getPaymentMethod
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a Payment Method Object.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/payment-methods/123
- lang: CLI
source: >
linode-cli payment-methods view 123
delete:
x-linode-grant: read_write
tags:
- Account
summary: Payment Method Delete
description: |
Deactivate the specified Payment Method.
The default Payment Method can not be deleted. To add a new default Payment Method, access the Payment Method
Add ([POST /account/payment-methods](/docs/api/account/#payment-method-add)) endpoint. To designate an existing
Payment Method as the default method, access the Payment Method Make Default
([POST /account/payment-methods/{paymentMethodId}/make-default](/docs/api/account/#payment-method-make-default))
endpoint.
operationId: deletePaymentMethod
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Payment Method deactivated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/account/payment-methods/123
- lang: CLI
source: >
linode-cli payment-methods delete 123
/account/payment-methods/{paymentMethodId}/make-default:
x-linode-cli-command: payment-methods
parameters:
- name: paymentMethodId
in: path
description: The ID of the Payment Method to make default.
required: true
schema:
type: integer
post:
servers:
- url: https://api.linode.com/v4
x-linode-grant: read_write
tags:
- Account
summary: Payment Method Make Default
description: |
Make the specified Payment Method the default method for automatically processing payments.
Removes the default status from any other Payment Method.
operationId: makePaymentMethodDefault
x-linode-cli-action: default
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Payment Method successfully set as the default method.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/payment-methods/123/make-default
- lang: CLI
source: >
linode-cli payment-methods default 123
/account/payments:
x-linode-cli-command: account
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
x-linode-grant: read_only
tags:
- Account
summary: Payments List
description: >
Returns a paginated list of Payments made on this Account.
operationId: getPayments
x-linode-cli-action: payments-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of Payment objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Payment'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/payments
- lang: CLI
source: >
linode-cli account payments-list
post:
x-linode-grant: read_write
tags:
- Account
summary: Payment Make
description: |
Makes a Payment to your Account.
* The requested amount is charged to the default Payment Method if no `payment_method_id` is specified.
* A `payment_submitted` event is generated when a payment is successfully submitted.
operationId: createPayment
x-linode-cli-action: payment-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the Payment you are making.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'200':
description: Payment submitted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'202':
$ref: '#/components/responses/AcceptedResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"cvv": "123",
"usd": "120.50",
"payment_method_id": 123
}' \
https://api.linode.com/v4/account/payments
- lang: CLI
source: >
linode-cli account payment-create \
--cvv 123 \
--usd 120.50 \
--payment_method_id 123
/account/payments/{paymentId}:
x-linode-cli-command: account
parameters:
- name: paymentId
in: path
description: The ID of the Payment to look up.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Account
summary: Payment View
description: >
Returns information about a specific Payment.
operationId: getPayment
x-linode-cli-action: payment-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A Payment object.
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/payments/123
- lang: CLI
source: >
linode-cli account payment-view 123
/account/payments/paypal:
x-linode-cli-command: account
post:
x-linode-grant: read_only
deprecated: true
x-linode-cli-skip: true
tags:
- Account
summary: PayPal Payment Stage
description: |
**Note**: This endpoint is disabled and no longer accessible. PayPal can be
designated as a Payment Method for automated payments using
[Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/#adding-a-new-payment-method).
operationId: createPayPalPayment
x-linode-cli-action: paypal-start
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The amount of the Payment to submit via PayPal.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayPal'
responses:
'200':
description: PayPal Payment staged.
content:
application/json:
schema:
type: object
properties:
payment_id:
type: string
description: >
The paypal-generated ID for this Payment. Used when
authorizing the Payment in PayPal's interface.
example: PAY-1234567890ABCDEFGHIJKLMN
checkout_token:
type: string
description: >
The checkout token generated for this Payment.
example: EC-1A2B3C4D5E6F7G8H9
readOnly: true
'299':
$ref: '#/components/responses/DeprecatedResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"usd": "120.50",
"redirect_url": "https://example.org",
"cancel_url": "https://example.org"
}' \
https://api.linode.com/v4/account/payments/paypal
- lang: CLI
source: >
linode-cli account paypal-start \
--cancel_url https://example.org \
--redirect_url https://example.org \
--usd 120.50
/account/payments/paypal/execute:
x-linode-cli-command: account
post:
x-linode-grant: read_write
deprecated: true
x-linode-cli-skip: true
tags:
- Account
summary: Staged/Approved PayPal Payment Execute
description: |
**Note**: This endpoint is disabled and no longer accessible. PayPal can be
designated as a Payment Method for automated payments using
[Cloud Manager](/docs/guides/manage-billing-in-cloud-manager/#adding-a-new-payment-method).
operationId: executePayPalPayment
x-linode-cli-action: paypal-execute
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The details of the Payment to execute.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayPalExecute'
responses:
'200':
description: PayPal Payment executed.
content:
application/json:
schema:
type: object
'202':
$ref: '#/components/responses/AcceptedResponse'
'299':
$ref: '#/components/responses/DeprecatedResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"payment_id": "PAY-1234567890ABCDEFGHIJKLMN",
"payer_id": "ABCDEFGHIJKLM"
}' \
https://api.linode.com/v4/account/payments/paypal
- lang: CLI
source: >
linode-cli account paypal-execute
/account/promo-codes:
x-linode-cli-command: account
post:
x-linode-grant: unrestricted only
tags:
- Account
summary: Promo Credit Add
description: |
Adds an expiring Promo Credit to your account.
The following restrictions apply:
* Your account must be less than 90 days old.
* There must not be an existing Promo Credit already on your account.
* The requesting User must be unrestricted. Use the User Update
([PUT /account/users/{username}](/docs/api/account/#user-update)) to change a User's restricted status.
* The `promo_code` must be valid and unexpired.
operationId: createPromoCredit
x-linode-cli-action: promo-add
security:
- personalAccessToken: []
- oauth:
- account:read_only
requestBody:
description: Enter a Promo Code to add its associated credit to your Account.
content:
application/json:
schema:
required:
- promo_code
type: object
properties:
promo_code:
type: string
minLength: 1
maxLength: 32
description: |
The Promo Code.
responses:
'200':
description: >
Promo Credit successfully added.
content:
application/json:
schema:
$ref: '#/components/schemas/Promotion'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"promo_code": "abcdefABCDEF1234567890"
}' \
https://api.linode.com/v4/account/promo-codes
- lang: CLI
source: >
linode-cli account \
promo-add \
--promo-code abcdefABCDEF1234567890
/account/service-transfers:
x-linode-cli-command: service-transfers
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Service Transfers List
description: >
Returns a collection of all created and accepted Service Transfers for this account, regardless of the user
that created or accepted the transfer.
This command can only be accessed by the unrestricted users of an account.
operationId: getServiceTransfers
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
Returns a paginated list of Service Transfer objects containing the details of all transfers that have been
created and accepted by this account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ServiceTransfer'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/service-transfers
- lang: CLI
source: >
linode-cli service-transfers \
list
post:
x-linode-grant: unrestricted only
tags:
- Account
summary: Service Transfer Create
description: |
Creates a transfer request for the specified services. A request can contain any of the specified service types
and any number of each service type. At this time, only Linodes can be transferred.
When created successfully, a confirmation email is sent to the account that created this transfer containing a
transfer token and instructions on completing the transfer.
When a transfer is [accepted](/docs/api/account/#service-transfer-accept), the requested services are moved to
the receiving account. Linode services will not experience interruptions due to the transfer process. Backups
for Linodes are transferred as well.
DNS records that are associated with requested services will not be transferred or updated. Please ensure that
associated DNS records have been updated or communicated to the recipient prior to the transfer.
A transfer can take up to three hours to complete once accepted. When a transfer is
completed, billing for transferred services ends for the sending account and begins for the receiving account.
This command can only be accessed by the unrestricted users of an account.
There are several conditions that must be met in order to successfully create a transfer request:
1. The account creating the transfer must not have a past due balance or active Terms of Service violation.
1. The service must be owned by the account that is creating the transfer.
1. The service must not be assigned to another Service Transfer that is pending or that has been accepted and is
incomplete.
1. Linodes must not:
* be assigned to a NodeBalancer, Firewall, VLAN, or Managed Service.
* have any attached Block Storage Volumes.
* have any shared IP addresses.
* have any assigned /56, /64, or /116 IPv6 ranges.
operationId: createServiceTransfer
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The services to include in this transfer request.
content:
application/json:
schema:
required:
- entities
type: object
properties:
entities:
$ref: '#/components/schemas/ServiceTransfer/properties/entities'
responses:
'200':
description: >
Returns a Service Transfer object for the request.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceTransfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"entities": {
"linodes": [
111,
222
]
}
}' \
https://api.linode.com/v4/account/service-transfers
- lang: CLI
source: >
linode-cli service-transfers \
create \
--entities.linodes 111 \
--entities.linodes 222
/account/service-transfers/{token}:
x-linode-cli-command: service-transfers
parameters:
- name: token
in: path
description: The UUID of the Service Transfer.
required: true
schema:
type: string
format: uuid
get:
x-linode-grant: unrestricted only
tags:
- Account
summary: Service Transfer View
description: |
Returns the details of the Service Transfer for the provided token.
While a transfer is pending, any unrestricted user *of any account* can access this command. After a
transfer has been accepted, it can only be viewed by unrestricted users of the accounts that created and
accepted the transfer. If cancelled or expired, only unrestricted users of the account that created the
transfer can view it.
operationId: getServiceTransfer
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
Returns a Service Transfer object containing the details of the transfer for the specified token.
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceTransfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/service-transfers/123E4567-E89B-12D3-A456-426614174000
- lang: CLI
source: >
linode-cli service-transfers \
view 123E4567-E89B-12D3-A456-426614174000
delete:
x-linode-grant: unrestricted only
tags:
- account
summary: Service Transfer Cancel
description: |
Cancels the Service Transfer for the provided token. Once cancelled, a transfer cannot be accepted or otherwise
acted on in any way. If cancelled in error, the transfer must be
[created](/docs/api/account/#service-transfer-create) again.
When cancelled, an email notification for the cancellation is sent to the account that created
this transfer. Transfers can not be cancelled if they are expired or have been accepted.
This command can only be accessed by the unrestricted users of the account that created this transfer.
operationId: deleteServiceTransfer
x-linode-cli-action: cancel
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: >
Service Transfer cancelled.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/account/service-transfers/123E4567-E89B-12D3-A456-426614174000
- lang: CLI
source: >
linode-cli service-transfers \
cancel 123E4567-E89B-12D3-A456-426614174000
/account/service-transfers/{token}/accept:
x-linode-cli-command: service-transfers
parameters:
- name: token
in: path
description: The UUID of the Service Transfer.
required: true
schema:
type: string
format: uuid
post:
x-linode-grant: unrestricted only
tags:
- Account
summary: Service Transfer Accept
description: |
Accept a Service Transfer for the provided token to receive the services included in the transfer to your
account. At this time, only Linodes can be transferred.
When accepted, email confirmations are sent to the accounts that created and accepted the transfer. A transfer
can take up to three hours to complete once accepted. Once a transfer is completed, billing for transferred
services ends for the sending account and begins for the receiving account.
This command can only be accessed by the unrestricted users of the account that receives the transfer. Users
of the same account that created a transfer cannot accept the transfer.
There are several conditions that must be met in order to accept a transfer request:
1. Only transfers with a `pending` status can be accepted.
1. The account accepting the transfer must have a registered payment method and must not have a past due
balance or other account limitations for the services to be transferred.
1. Both the account that created the transfer and the account that is accepting the transfer must not have any
active Terms of Service violations.
1. The service must still be owned by the account that created the transfer.
1. Linodes must not:
* be assigned to a NodeBalancer, Firewall, VLAN, or Managed Service.
* have any attached Block Storage Volumes.
* have any shared IP addresses.
* have any assigned /56, /64, or /116 IPv6 ranges.
Any and all of the above conditions must be cured and maintained by the relevant account prior to the
transfer's expiration to allow the transfer to be accepted by the receiving account.
operationId: acceptServiceTransfer
x-linode-cli-action: accept
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: >
Service Transfer accepted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/service-transfers/123E4567-E89B-12D3-A456-426614174000/accept
- lang: CLI
source: >
linode-cli service-transfers \
accept 123E4567-E89B-12D3-A456-426614174000
/account/settings:
x-linode-cli-command: account
get:
x-linode-grant: read_only
tags:
- Account
summary: Account Settings View
description: >
Returns information related to
your Account settings: Managed service subscription, Longview
subscription, and network helper.
operationId: getAccountSettings
x-linode-cli-action: settings
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a single Account settings object.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountSettings'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/settings
- lang: CLI
source: >
linode-cli account settings
put:
x-linode-grant: read_write
tags:
- Account
summary: Account Settings Update
description: >
Updates your Account settings.
To update your Longview subscription plan, send a request to [Update Longview Plan](/docs/api/longview/#longview-plan-update).
operationId: updateAccountSettings
x-linode-cli-action: settings-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Update Account settings information.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountSettings'
responses:
'200':
description: The updated Account settings.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountSettings'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"network_helper": true,
}' \
https://api.linode.com/v4/account/settings
- lang: CLI
source: >
linode-cli account settings-update \
--network_helper false
/account/settings/managed-enable:
x-linode-cli-command: account
post:
x-linode-grant: read_write
tags:
- Account
summary: Linode Managed Enable
description: >
Enables Linode Managed for the entire account and sends a welcome email to the account's associated
email address. Linode Managed can monitor any service or software stack reachable over TCP or HTTP. See
our [Linode Managed guide](/docs/platform/linode-managed/)
to learn more.
operationId: enableAccountManaged
x-linode-cli-action: enable-managed
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Managed services enabled for account.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/account/settings/managed-enable
- lang: CLI
source: >
linode-cli account enable-managed
/account/transfer:
x-linode-cli-command: account
get:
x-linode-grant: read_only
tags:
- Account
summary: Network Utilization View
description: >
Returns a Transfer object showing your network utilization,
in GB, for the current month.
operationId: getTransfer
x-linode-cli-action: transfer
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a single Transfer object.
content:
application/json:
schema:
$ref: '#/components/schemas/Transfer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/transfer
- lang: CLI
source: >
linode-cli account transfer
/account/users:
x-linode-cli-command: users
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Account
summary: Users List
description: |
Returns a paginated list of Users on your Account.
This command can only be accessed by the unrestricted users of an account.
Users may access all or part of your Account based on their restricted status and grants. An unrestricted User may access everything on the account, whereas restricted User may only access entities or perform actions they've been given specific grants to.
operationId: getUsers
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of Users.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/users
- lang: CLI
source: >
linode-cli users list
post:
x-linode-grant: unrestricted only
tags:
- Account
summary: User Create
description: |
Creates a User on your Account. Once created, a confirmation message containing
password creation and login instructions is sent to the User's email address.
This command can only be accessed by the unrestricted users of an account.
The User's account access is determined by whether or not they are restricted,
and what grants they have been given.
operationId: createUser
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the User to create.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/User'
required:
- username
- email
responses:
'200':
description: New User created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"username": "example_user",
"email": "person@place.com",
"restricted": true
}' \
https://api.linode.com/v4/account/users
- lang: CLI
source: >
linode-cli users create \
--username example_user \
--email example_user@linode.com \
--restricted true
/account/users/{username}:
x-linode-cli-command: users
parameters:
- name: username
in: path
description: The username to look up.
required: true
schema:
type: string
get:
x-linode-grant: unrestricted only
tags:
- Account
summary: User View
description: |
Returns information about a single User on your Account.
This command can only be accessed by the unrestricted users of an account.
operationId: getUser
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested User object
content:
application/json:
schema:
$ref: '#/components/schemas/User'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/users/example_user
- lang: CLI
source: >
linode-cli users view example_user
put:
x-linode-grant: unrestricted only
tags:
- Account
summary: User Update
description: |
Update information about a User on your Account. This can be used to
change the restricted status of a User. When making a User restricted,
no grants will be configured by default and you must then set up grants
in order for the User to access anything on the Account.
This command can only be accessed by the unrestricted users of an account.
operationId: updateUser
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The information to update.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
'200':
description: User updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"username": example_user,
"email": example@linode.com,
"restricted": true
}' \
https://api.linode.com/v4/account/users/example_user
- lang: CLI
source: >
linode-cli users update example_user \
--username example_user \
--email example@linode.com \
--restricted true
delete:
x-linode-grant: unrestricted only
tags:
- Account
summary: User Delete
description: |
Deletes a User. The deleted User will be immediately logged out and
may no longer log in or perform any actions. All of the User's Grants
will be removed.
This command can only be accessed by the unrestricted users of an account.
operationId: deleteUser
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: User deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/account/users/example_user
- lang: CLI
source: >
linode-cli users delete example_user
/account/users/{username}/grants:
x-linode-cli-command: users
parameters:
- name: username
in: path
description: The username to look up.
required: true
schema:
type: string
get:
x-linode-grant: unrestricted only
tags:
- Account
summary: User's Grants View
description: |
Returns the full grants structure for the specified account User
(other than the account owner, see below for details). This includes all entities
on the Account alongside the level of access this User has to each of them.
This command can only be accessed by the unrestricted users of an account.
The current authenticated User, including the account owner, may view their
own grants at the [/profile/grants](/docs/api/profile/#grants-list)
endpoint, but will not see entities that they do not have access to.
operationId: getUserGrants
x-linode-cli-action: grants
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The User's grants.
content:
application/json:
schema:
$ref: '#/components/schemas/GrantsResponse'
'204':
description: >
This is an unrestricted User, and therefore has no grants to return.
This User may access everything on the Account and perform all actions.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/account/users/example_user/grants
put:
x-linode-grant: unrestricted only
tags:
- Account
summary: User's Grants Update
description: |
Update the grants a User has. This can be used to give a User access
to new entities or actions, or take access away. You do not need to
include the grant for every entity on the Account in this request; any
that are not included will remain unchanged.
This command can only be accessed by the unrestricted users of an account.
operationId: updateUserGrants
x-linode-cli-action: update-grants
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The grants to update. Omitted grants will be left unchanged.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GrantsResponse'
responses:
'200':
description: Grants updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GrantsResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"global": {
"add_linodes": true,
"add_nodebalancers": false,
"add_databases": true;
"add_domains": true,
"add_longview": false,
"add_stackscripts": true,
"longview_subscription": true,
"add_images": true,
"add_volumes": true,
"add_firewalls": true,
"account_access": "read_only",
"cancel_account": false
},
"domain": [
{
"id": 123,
"permissions": "read_only"
}
],
"image": [
{
"id": 123,
"permissions": "read_only"
}
],
"linode": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 234,
"permissions": "read_write"
},
{
"id": 345,
"permissions": "read_only"
},
],
"longview": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 234,
"permissions": "read_write"
}
],
"nodebalancer": [
{
"id": 123,
"permissions": "read_write"
}
],
"stackscript": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 124,
"permissions": "read_write"
}
],
"volume": [
{
"id": 123,
"permissions": "read_only"
}
]
}' \
https://api.linode.com/v4/account/users/example_user/grants
/databases/engines:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed Database Engines List
operationId: getDatabasesEngines
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: engines
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all available Managed Database engine types and versions. Engine IDs are used when creating new Managed Databases.
responses:
'200':
description: Returns a paginated list of all available Managed Database engines and versions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseEngine'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/databases/engines/
- lang: CLI
source: >
linode-cli databases engines
/databases/engines/{engineId}:
parameters:
- name: engineId
in: path
description: The ID of the Managed Database engine.
required: true
schema:
type: string
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed Database Engine View
operationId: getDatabasesEngine
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: engine-view
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display information for a single Managed Database engine type and version.
responses:
'200':
description: Returns information for a single Managed Database engine type and version.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseEngine'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/databases/engines/mysql/5.7.30
- lang: CLI
source: >
linode-cli databases engine-view mysql/5.7.30
/databases/instances:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed Databases List All
operationId: getDatabasesInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all Managed Databases that are accessible by your User, regardless of engine type.
For more detailed information on a particular Database instance, make a request to its `instance_uri`.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns a paginated list of all accessible Managed Databases on your Account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Database'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/instances
- lang: CLI
source: >
linode-cli databases list
/databases/mongodb/instances:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed MongoDB Databases List
operationId: getDatabasesMongoDBInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all accessible Managed MongoDB Databases.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns a paginated list of all accessible Managed MongoDB Databases on your Account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseMongoDB'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/
- lang: CLI
source: >
linode-cli databases mongodb-list
# post:
# tags:
# - Databases
# summary: Managed MongoDB Database Create
# operationId: postDatabasesMongoDBInstances
# servers:
# - url: https://api.linode.com/v4
# - url: https://api.linode.com/v4beta
# x-linode-cli-action: mongodb-create
# x-linode-grant: add_databases
# description: |
# Provision a Managed MongoDB Database.
# Restricted Users must have the `add_databases` grant to use this command.
# New instances can take approximately 15 to 30 minutes to provision.
# The `allow_list` is used to control access to the Managed Database.
# * IP addresses on this list can access the Managed Database. All other sources are blocked.
# * Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
# All Managed Databases include automatic, daily backups. Up to seven backups are automatically stored for each Managed Database, providing restore points for each day of the past week.
# All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed MongoDB Database during configurable maintenance windows.
# * If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
# * **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
# * To modify update the maintenance window for a Database, use the **Managed MongoDB Database Update** ([PUT /databases/mongodb/instances/{instanceId}](/docs/api/databases/#managed-mongodb-database-update)) command.
# **Note**: Managed MongoDB clusters are currently accessible over public IP addresses. To provide an additional layer of protection, support for private IP addresses is in development.
# security:
# - personalAccessToken: []
# - oauth:
# - databases:read_write
# requestBody:
# description: Information about the Managed MongoDB Database you are creating.
# x-linode-cli-allowed-defaults:
# - region
# - type
# required: true
# content:
# application/json:
# schema:
# $ref: '#/components/schemas/DatabaseMongoDBRequest'
# responses:
# '200':
# description: A new Managed MongoDB Database is provisioning.
# content:
# application/json:
# schema:
# $ref: '#/components/schemas/DatabaseMongoDB'
# default:
# $ref: '#/components/responses/ErrorResponse'
# x-code-samples:
# - lang: Shell
# source: >
# curl -H "Content-Type: application/json" \
# -H "Authorization: Bearer $TOKEN" \
# -X POST -d '{
# "label": "example-db",
# "region": "us-east",
# "type": "g6-dedicated-2",
# "cluster_size": 3,
# "engine": "mongodb/4.4.10",
# "encrypted": false,
# "ssl_connection": false,
# "replica_set": "example-replica-set",
# "compression_type": "none",
# "storage_engine": "wiredtiger",
# "allow_list": [
# "203.0.113.1",
# "192.0.1.0/24"
# ]
# }' \
# https://api.linode.com/v4/databases/mongodb/instances
# - lang: CLI
# source: >
# linode-cli databases mongodb-create \
# --label example-db \
# --region us-east \
# --type g6-dedicated-2 \
# --cluster_size 3 \
# --engine mongodb/4.4.10 \
# --encrypted false \
# --ssl_connection true \
# --replica_set example-replica-set \
# --storage_engine wiredtiger \
# --compression_type none \
# --allow_list 203.0.113.1 \
# --allow_list 192.0.1.0/24
/databases/mongodb/instances/{instanceId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MongoDB Database View
operationId: getDatabasesMongoDBInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-view
x-linode-grant: read_only
description: |
Display information for a single, accessible Managed MongoDB Database.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns information for a single Managed MongoDB Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMongoDB'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/123
- lang: CLI
source: >
linode-cli databases mongodb-view 123
delete:
tags:
- Databases
summary: Managed MongoDB Database Delete
operationId: deleteDatabasesMongoDBInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-delete
x-linode-grant: read_write
description: |
Remove a Managed MongoDB Database from your Account.
Requires `read_write` access to the Database.
The Database must have an `active`, `failed`, or `degraded` status to perform this command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed MongoDB Database successfully deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/mongodb/instances/123
- lang: CLI
source: >
linode-cli databases mongodb-delete 123
put:
tags:
- Databases
summary: Managed MongoDB Database Update
operationId: putDatabasesMongoDBInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-update
x-linode-grant: read_write
description: |
Update a Managed MongoDB Database.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
Updating addresses in the `allow_list` overwrites any existing addresses.
* IP addresses on this list can access the Managed Database. All other sources are blocked.
* Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
* **Note**: Updates to the `allow_list` may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.
All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed MongoDB Database. The maintenance window for these updates is configured with the Managed Database's `updates` property.
* If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Updated information for the Managed MongoDB Database.
required: true
content:
application/json:
schema:
type: object
description: Updated information for the Managed MongoDB Database.
properties:
label:
$ref: '#/components/schemas/DatabaseMongoDBRequest/properties/label'
allow_list:
$ref: '#/components/schemas/DatabaseMongoDBRequest/properties/allow_list'
updates:
$ref: '#/components/schemas/DatabaseMongoDB/properties/updates'
responses:
'200':
description: Managed Database updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMongoDB'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "example-db",
"allow_list": [
"203.0.113.1",
"192.0.1.0/24"
],
"updates" = {
"frequency": "monthly",
"duration": 3,
"hour_of_day": 12,
"day_of_week": 4,
"week_of_month": 3,
}
}' \
https://api.linode.com/v4/databases/mongodb/instances/123
- lang: CLI
source: >
linode-cli databases mongodb-update 123 \
--label example-db \
--allow_list 203.0.113.1 \
--allow_list 192.0.1.0/24 \
--updates.frequency monthly \
--updates.duration 3 \
--updates.hour_of_day 12 \
--updates.day_of_week 4 \
--updates.week_of_month 3
/databases/mongodb/instances/{instanceId}/backups:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MongoDB Database Backups List
operationId: getDatabasesMongoDBInstanceBackups
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-backups-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all backups for an accessible Managed MongoDB Database.
The Database must not be provisioning to perform this command.
Database `auto` type backups are created every 24 hours at 0:00 UTC. Each `auto` backup is retained for 7 days.
Database `snapshot` type backups are created by accessing the **Managed MongoDB Database Backup Snapshot Create** ([POST /databases/mongodb/instances/{instanceId}/backups](/docs/api/databases/#managed-mongodb-database-backup-snapshot-create)) command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a paginated list of backups for the Managed MongoDB Database.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/123/backups
- lang: CLI
source: >
linode-cli databases mongodb-backups-list 123
post:
tags:
- Databases
summary: Managed MongoDB Database Backup Snapshot Create
operationId: postDatabasesMongoDBInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-backup-snapshot
x-linode-grant: read_write
description: |
Creates a snapshot backup of a Managed MongoDB Database.
Requires `read_write` access to the Database.
Backups generated by this command have the type `snapshot`. Snapshot backups may take several minutes to complete, after which they will be accessible to view or restore.
The Database must have an `active` status to perform this command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Information about the snapshot backup to create.
content:
application/json:
schema:
required:
- label
type: object
properties:
label:
type: string
minLength: 3
maxLength: 64
description: |
The label for the Database snapshot backup.
* Must use only letters, numbers, underscores, dashes, and periods.
* Must begin and end with a letter or number.
* Must not include two dashes, underscores, or periods in a row.
example: db-snapshot
target:
type: string
enum:
- primary
- secondary
default: primary
description: |
The Database cluster target.
If the Database is a high availability cluster, choosing `secondary` creates a snapshot backup of a replica node.
example: primary
responses:
'200':
description: Database snapshot backup request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "db-snapshot",
"target": "primary"
}' \
https://api.linode.com/v4/databases/mongodb/instances/123/backups/
- lang: CLI
source: >
linode-cli databases mongodb-backup-snapshot 123 \
--label db-snapshot \
--target primary
/databases/mongodb/instances/{instanceId}/backups/{backupId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed MongoDB Database backup.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MongoDB Database Backup View
operationId: getDatabasesMongoDBInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-backup-view
x-linode-grant: read_only
description: |
Display information for a single backup for an accessible Managed MongoDB Database.
The Database must not be provisioning to perform this command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a single backup for the Managed MongoDB Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases mongodb-backup-view 123 456
delete:
tags:
- Databases
summary: Managed MongoDB Database Backup Delete
operationId: deleteDatabaseMongoDBInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-backup-delete
description: |
Delete a single backup for an accessible Managed MongoDB Database.
Requires `read_write` access to the Database.
The Database must not be provisioning to perform this command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to delete Database backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/mongodb/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases mongodb-backup-delete 123 456
/databases/mongodb/instances/{instanceId}/backups/{backupId}/restore:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed MongoDB Database backup.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MongoDB Database Backup Restore
operationId: postDatabasesMongoDBInstanceBackupRestore
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-backup-restore
x-linode-grant: read_write
description: |
Restore a backup to a Managed MongoDB Database on your Account.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**: Restoring from a backup will erase all existing data on the database instance and replace it with backup data.
**Note**: Currently, restoring a backup after resetting Managed Database credentials results in a failed cluster. Please contact Customer Support if this occurs.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to restore backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mongodb/instances/123/backups/456/restore
- lang: CLI
source: >
linode-cli databases mongodb-backup-restore 123 456
/databases/mongodb/instances/{instanceId}/credentials:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MongoDB Database Credentials View
operationId: getDatabasesMongoDBInstanceCredentials
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-creds-view
x-linode-grant: read_only
description: |
Display the root username and password for an accessible Managed MongoDB Database.
The Database must have an `active` status to perform this command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Managed Database root username and password.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseCredentials'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/123/credentials/
- lang: CLI
source: >
linode-cli databases mongodb-creds-view 123
/databases/mongodb/instances/{instanceId}/credentials/reset:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MongoDB Database Credentials Reset
operationId: postDatabasesMongoDBInstanceCredentialsReset
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-creds-reset
x-linode-grant: read_write
description: |
Reset the root password for a Managed MongoDB Database.
Requires `read_write` access to the Database.
A new root password is randomly generated and accessible with the **Managed MongoDB Database Credentials View** ([GET /databases/mongodb/instances/{instanceId}/credentials](/docs/api/databases/#managed-mongodb-database-credentials-view)) command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
**Note**: Note that it may take several seconds for credentials to reset.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance credentials successfully reset.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mongodb/instances/123/credentials/reset
- lang: CLI
source: >
linode-cli databases mongodb-creds-reset 123
/databases/mongodb/instances/{instanceId}/ssl:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MongoDB Database SSL Certificate View
operationId: getDatabasesMongoDBInstanceSSL
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-ssl-cert
x-linode-grant: read_only
description: |
Display the SSL CA certificate for an accessible Managed MongoDB Database.
The Database must have an `active` status to perform this command.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns the SSL CA certificate of a single Managed MongoDB Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseSSL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mongodb/instances/123/ssl
- lang: CLI
source: >
linode-cli databases mongodb-ssl-cert 123
/databases/mongodb/instances/{instanceId}/patch:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MongoDB Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MongoDB Database Patch
operationId: postDatabasesMongoDBInstancePatch
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mongodb-patch
x-linode-grant: read_write
description: |
Apply security patches and updates to the underlying operating system of the Managed MongoDB Database. This function runs during regular maintenance windows, which are configurable with the **Managed MongoDB Database Update** ([PUT /databases/mongodb/instances/{instanceId}](/docs/api/databases/#managed-mongodb-database-update)) command.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**:
* If your database cluster is configured with a single node, you will experience downtime during this maintenance. Consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
**Note**: New MongoDB Databases cannot currently be created.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance patch request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mongodb/instances/123/patch
- lang: CLI
source: >
linode-cli databases mongodb-patch 123
/databases/mysql/instances:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed MySQL Databases List
operationId: getDatabasesMySQLInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all accessible Managed MySQL Databases.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns a paginated list of all accessible Managed MySQL Databases on your Account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseMySQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/
- lang: CLI
source: >
linode-cli databases mysql-list
post:
tags:
- Databases
summary: Managed MySQL Database Create
operationId: postDatabasesMySQLInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-create
x-linode-grant: add_databases
description: |
Provision a Managed MySQL Database.
Restricted Users must have the `add_databases` grant to use this command.
New instances can take approximately 15 to 30 minutes to provision.
The `allow_list` is used to control access to the Managed Database.
* IP addresses on this list can access the Managed Database. All other sources are blocked.
* Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
All Managed Databases include automatic, daily backups. Up to seven backups are automatically stored for each Managed Database, providing restore points for each day of the past week.
All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed MySQL Database during configurable maintenance windows.
* If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then [migrate your databases](/docs/products/databases/managed-databases/guides/migrate-mysql/) from the original Managed Database cluster to the new one.
* To modify update the maintenance window for a Database, use the **Managed MySQL Database Update** ([PUT /databases/mysql/instances/{instanceId}](/docs/api/databases/#managed-mysql-database-update)) command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Information about the Managed MySQL Database you are creating.
x-linode-cli-allowed-defaults:
- region
- type
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMySQLRequest'
responses:
'200':
description: A new Managed MySQL Database is provisioning.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMySQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "example-db",
"region": "us-east",
"type": "g6-dedicated-2",
"cluster_size": 3,
"engine": "mysql/8.0.26",
"encrypted": false,
"ssl_connection": true,
"replication_type": "semi_synch",
"allow_list": [
"203.0.113.1",
"192.0.1.0/24"
]
}' \
https://api.linode.com/v4/databases/mysql/instances
- lang: CLI
source: >
linode-cli databases mysql-create \
--label example-db1 \
--region us-east \
--type g6-dedicated-2 \
--cluster_size 3 \
--engine mysql/8.0.26 \
--encrypted false \
--ssl_connection false \
--replication_type semi_synch \
--allow_list 203.0.113.1 \
--allow_list 192.0.1.0/24
/databases/mysql/instances/{instanceId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MySQL Database View
operationId: getDatabasesMySQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-view
x-linode-grant: read_only
description: |
Display information for a single, accessible Managed MySQL Database.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns information for a single Managed MySQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMySQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/123
- lang: CLI
source: >
linode-cli databases mysql-view 123
delete:
tags:
- Databases
summary: Managed MySQL Database Delete
operationId: deleteDatabasesMySQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-delete
x-linode-grant: read_write
description: |
Remove a Managed MySQL Database from your Account.
Requires `read_write` access to the Database.
The Database must have an `active`, `failed`, or `degraded` status to perform this command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed MySQL Database successfully deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/mysql/instances/123
- lang: CLI
source: >
linode-cli databases mysql-delete 123
put:
tags:
- Databases
summary: Managed MySQL Database Update
operationId: putDatabasesMySQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-update
x-linode-grant: read_write
description: |
Update a Managed MySQL Database.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
Updating addresses in the `allow_list` overwrites any existing addresses.
* IP addresses on this list can access the Managed Database. All other sources are blocked.
* Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
* **Note**: Updates to the `allow_list` may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.
All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed MySQL Database. The maintenance window for these updates is configured with the Managed Database's `updates` property.
* If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then [migrate your databases](/docs/products/databases/managed-databases/guides/migrate-mysql/) from the original Managed Database cluster to the new one.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Updated information for the Managed MySQL Database.
required: true
content:
application/json:
schema:
type: object
description: Updated information for the Managed MySQL Database.
properties:
label:
$ref: '#/components/schemas/DatabaseMySQLRequest/properties/label'
allow_list:
$ref: '#/components/schemas/DatabaseMySQLRequest/properties/allow_list'
updates:
$ref: '#/components/schemas/DatabaseMySQL/properties/updates'
responses:
'200':
description: Managed Database updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseMySQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "example-db",
"allow_list": [
"203.0.113.1",
"192.0.1.0/24"
],
"updates" = {
"frequency": "monthly",
"duration": 3,
"hour_of_day": 12,
"day_of_week": 4,
"week_of_month": 3,
}
}' \
https://api.linode.com/v4/databases/mysql/instances/123
- lang: CLI
source: >
linode-cli databases mysql-update 123 \
--label example-db \
--allow_list 203.0.113.1 \
--allow_list 192.0.1.0/24 \
--updates.frequency monthly \
--updates.duration 3 \
--updates.hour_of_day 12 \
--updates.day_of_week 4 \
--updates.week_of_month 3
/databases/mysql/instances/{instanceId}/backups:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MySQL Database Backups List
operationId: getDatabasesMySQLInstanceBackups
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-backups-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all backups for an accessible Managed MySQL Database.
The Database must not be provisioning to perform this command.
Database `auto` type backups are created every 24 hours at 0:00 UTC. Each `auto` backup is retained for 7 days.
Database `snapshot` type backups are created by accessing the **Managed MySQL Database Backup Snapshot Create** ([POST /databases/mysql/instances/{instanceId}/backups](/docs/api/databases/#managed-mysql-database-backup-snapshot-create)) command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a paginated list of backups for the Managed MySQL Database.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/123/backups
- lang: CLI
source: >
linode-cli databases mysql-backups-list 123
post:
tags:
- Databases
summary: Managed MySQL Database Backup Snapshot Create
operationId: postDatabasesMySQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-backup-snapshot
x-linode-grant: read_write
description: |
Creates a snapshot backup of a Managed MySQL Database.
Requires `read_write` access to the Database.
Backups generated by this command have the type `snapshot`. Snapshot backups may take several minutes to complete, after which they will be accessible to view or restore.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Information about the snapshot backup to create.
content:
application/json:
schema:
required:
- label
type: object
properties:
label:
type: string
minLength: 3
maxLength: 64
description: |
The label for the Database snapshot backup.
* Must use only letters, numbers, underscores, dashes, and periods.
* Must begin and end with a letter or number.
* Must not include two dashes, underscores, or periods in a row.
example: db-snapshot
target:
type: string
enum:
- primary
- secondary
default: primary
description: |
The Database cluster target.
If the Database is a high availability cluster, choosing `secondary` creates a snapshot backup of a replica node.
example: primary
responses:
'200':
description: Database snapshot backup request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "db-snapshot",
"target": "primary"
}' \
https://api.linode.com/v4/databases/mysql/instances/123/backups/
- lang: CLI
source: >
linode-cli databases mysql-backup-snapshot 123 \
--label db-snapshot \
--target primary
/databases/mysql/instances/{instanceId}/backups/{backupId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed MySQL Database backup.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MySQL Database Backup View
operationId: getDatabasesMySQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-backup-view
x-linode-grant: read_only
description: |
Display information for a single backup for an accessible Managed MySQL Database.
The Database must not be provisioning to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a single backup for the Managed MySQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases mysql-backup-view 123 456
delete:
tags:
- Databases
summary: Managed MySQL Database Backup Delete
operationId: deleteDatabaseMySQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-backup-delete
description: |
Delete a single backup for an accessible Managed MySQL Database.
Requires `read_write` access to the Database.
The Database must not be provisioning to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to delete Database backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/mysql/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases mysql-backup-delete 123 456
/databases/mysql/instances/{instanceId}/backups/{backupId}/restore:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed MySQL Database backup.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MySQL Database Backup Restore
operationId: postDatabasesMySQLInstanceBackupRestore
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-backup-restore
x-linode-grant: read_write
description: |
Restore a backup to a Managed MySQL Database on your Account.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**: Restoring from a backup will erase all existing data on the database instance and replace it with backup data.
**Note**: Currently, restoring a backup after resetting Managed Database credentials results in a failed cluster. Please contact Customer Support if this occurs.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to restore backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mysql/instances/123/backups/456/restore
- lang: CLI
source: >
linode-cli databases mysql-backup-restore 123 456
/databases/mysql/instances/{instanceId}/credentials:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MySQL Database Credentials View
operationId: getDatabasesMySQLInstanceCredentials
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-creds-view
x-linode-grant: read_only
description: |
Display the root username and password for an accessible Managed MySQL Database.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Managed Database root username and password.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseCredentials'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/123/credentials/
- lang: CLI
source: >
linode-cli databases mysql-creds-view 123
/databases/mysql/instances/{instanceId}/credentials/reset:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MySQL Database Credentials Reset
operationId: postDatabasesMySQLInstanceCredentialsReset
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-creds-reset
x-linode-grant: read_write
description: |
Reset the root password for a Managed MySQL Database.
Requires `read_write` access to the Database.
A new root password is randomly generated and accessible with the **Managed MySQL Database Credentials View** ([GET /databases/mysql/instances/{instanceId}/credentials](/docs/api/databases/#managed-mysql-database-credentials-view)) command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
**Note**: Note that it may take several seconds for credentials to reset.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance credentials successfully reset.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mysql/instances/123/credentials/reset
- lang: CLI
source: >
linode-cli databases mysql-creds-reset 123
/databases/mysql/instances/{instanceId}/ssl:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed MySQL Database SSL Certificate View
operationId: getDatabasesMySQLInstanceSSL
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-ssl-cert
x-linode-grant: read_only
description: |
Display the SSL CA certificate for an accessible Managed MySQL Database.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns the SSL CA certificate of a single Managed MySQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseSSL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/mysql/instances/123/ssl
- lang: CLI
source: >
linode-cli databases mysql-ssl-cert 123
/databases/mysql/instances/{instanceId}/patch:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed MySQL Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed MySQL Database Patch
operationId: postDatabasesMySQLInstancePatch
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: mysql-patch
x-linode-grant: read_write
description: |
Apply security patches and updates to the underlying operating system of the Managed MySQL Database. This function runs during regular maintenance windows, which are configurable with the **Managed MySQL Database Update** ([PUT /databases/mysql/instances/{instanceId}](/docs/api/databases/#managed-mysql-database-update)) command.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**
* If your database cluster is configured with a single node, you will experience downtime during this maintenance. Consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then [migrate your databases](/docs/products/databases/managed-databases/guides/migrate-mysql/) from the original Managed Database cluster to the new one.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance patch request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/mysql/instances/123/patch
- lang: CLI
source: >
linode-cli databases mysql-patch 123
/databases/postgresql/instances:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed PostgreSQL Databases List
operationId: getDatabasesPostgreSQLInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all accessible Managed PostgreSQL Databases.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns a paginated list of all accessible Managed PostgreSQL Databases on your Account.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabasePostgreSQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/
- lang: CLI
source: >
linode-cli databases postgresql-list
post:
tags:
- Databases
summary: Managed PostgreSQL Database Create
operationId: postDatabasesPostgreSQLInstances
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-create
x-linode-grant: add_databases
description: |
Provision a Managed PostgreSQL Database.
Restricted Users must have the `add_databases` grant to use this command.
New instances can take approximately 15 to 30 minutes to provision.
The `allow_list` is used to control access to the Managed Database.
* IP addresses on this list can access the Managed Database. All other sources are blocked.
* Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
All Managed Databases include automatic, daily backups. Up to seven backups are automatically stored for each Managed Database, providing restore points for each day of the past week.
All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed PostgreSQL Database during configurable maintenance windows.
* If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
* To modify update the maintenance window for a Database, use the **Managed PostgreSQL Database Update** ([PUT /databases/postgresql/instances/{instanceId}](/docs/api/databases/#managed-postgresql-database-update)) command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Information about the Managed PostgreSQL Database you are creating.
x-linode-cli-allowed-defaults:
- region
- type
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DatabasePostgreSQLRequest'
responses:
'200':
description: A new Managed PostgreSQL Database is provisioning.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabasePostgreSQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "example-db",
"region": "us-east",
"type": "g6-dedicated-2",
"cluster_size": 3,
"engine": "postgresql/13.2",
"encrypted": false,
"ssl_connection": false,
"replication_type": "asynch",
"replication_commit_type": "local",
"allow_list": [
"203.0.113.1",
"192.0.1.0/24"
]
}' \
https://api.linode.com/v4/databases/postgresql/instances
- lang: CLI
source: >
linode-cli databases postgresql-create \
--label example-db \
--region us-east \
--type g6-dedicated-2 \
--cluster_size 3 \
--engine postgresql/13.2 \
--encrypted false \
--ssl_connection false \
--replication_type asynch \
--replication_commit_type local \
--allow_list 203.0.113.1 \
--allow_list 192.0.1.0/24
/databases/postgresql/instances/{instanceId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed PostgreSQL Database View
operationId: getDatabasesPostgreSQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-view
x-linode-grant: read_only
description: |
Display information for a single, accessible Managed PostgreSQL Database.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns information for a single Managed PostgreSQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabasePostgreSQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/123
- lang: CLI
source: >
linode-cli databases postgresql-view 123
delete:
tags:
- Databases
summary: Managed PostgreSQL Database Delete
operationId: deleteDatabasesPostgreSQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-delete
x-linode-grant: read_write
description: |
Remove a Managed PostgreSQL Database from your Account.
Requires `read_write` access to the Database.
The Database must have an `active`, `failed`, or `degraded` status to perform this command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed PostgreSQL Database successfully deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/postgresql/instances/123
- lang: CLI
source: >
linode-cli databases postgresql-delete 123
put:
tags:
- Databases
summary: Managed PostgreSQL Database Update
operationId: putDatabasesPostgreSQLInstance
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-update
x-linode-grant: read_write
description: |
Update a Managed PostgreSQL Database.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
Updating addresses in the `allow_list` overwrites any existing addresses.
* IP addresses on this list can access the Managed Database. All other sources are blocked.
* Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database.
* **Note**: Updates to the `allow_list` may take a short period of time to complete, making this command inappropriate for rapid successive updates to this property.
All Managed Databases include automatic patch updates, which apply security patches and updates to the underlying operating system of the Managed PostgreSQL Database. The maintenance window for these updates is configured with the Managed Database's `updates` property.
* If your database cluster is configured with a single node, you will experience downtime during this maintenance window when any updates occur. It's recommended that you adjust this window to match a time that will be the least disruptive for your application and users. You may also want to consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Updated information for the Managed PostgreSQL Database.
required: true
content:
application/json:
schema:
type: object
description: Updated information for the Managed PostgreSQL Database.
properties:
label:
$ref: '#/components/schemas/DatabasePostgreSQLRequest/properties/label'
allow_list:
$ref: '#/components/schemas/DatabasePostgreSQLRequest/properties/allow_list'
updates:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/updates'
responses:
'200':
description: Managed Database updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabasePostgreSQL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "example-db",
"allow_list": [
"203.0.113.1",
"192.0.1.0/24"
],
"updates" = {
"frequency": "monthly",
"duration": 3,
"hour_of_day": 12,
"day_of_week": 4,
"week_of_month": 3,
}
}' \
https://api.linode.com/v4/databases/postgresql/instances/123
- lang: CLI
source: >
linode-cli databases postgresql-update 123 \
--label example-db \
--allow_list 203.0.113.1 \
--allow_list 192.0.1.0/24 \
--updates.frequency monthly \
--updates.duration 3 \
--updates.hour_of_day 12 \
--updates.day_of_week 4 \
--updates.week_of_month 3
/databases/postgresql/instances/{instanceId}/backups:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed PostgreSQL Database Backups List
operationId: getDatabasesPostgreSQLInstanceBackups
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-backups-list
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all backups for an accessible Managed PostgreSQL Database.
The Database must not be provisioning to perform this command.
Database `auto` type backups are created every 24 hours at 0:00 UTC. Each `auto` backup is retained for 7 days.
Database `snapshot` type backups are created by accessing the **Managed PostgreSQL Database Backup Snapshot Create** ([POST /databases/postgresql/instances/{instanceId}/backups](/docs/api/databases/#managed-postgresql-database-backup-snapshot-create)) command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a paginated list of backups for the Managed PostgreSQL Database.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/123/backups
- lang: CLI
source: >
linode-cli databases postgresql-backups-list 123
post:
tags:
- Databases
summary: Managed PostgreSQL Database Backup Snapshot Create
operationId: postDatabasesPostgreSQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-backup-snapshot
x-linode-grant: read_write
description: |
Creates a snapshot backup of a Managed PostgreSQL Database.
Requires `read_write` access to the Database.
Backups generated by this command have the type `snapshot`. Snapshot backups may take several minutes to complete, after which they will be accessible to view or restore.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
requestBody:
description: Information about the snapshot backup to create.
content:
application/json:
schema:
required:
- label
type: object
properties:
label:
type: string
minLength: 3
maxLength: 64
description: |
The label for the Database snapshot backup.
* Must use only letters, numbers, underscores, dashes, and periods.
* Must begin and end with a letter or number.
* Must not include two dashes, underscores, or periods in a row.
example: db-snapshot
target:
type: string
enum:
- primary
- secondary
default: primary
description: |
The Database cluster target.
If the Database is a high availability cluster, choosing `secondary` creates a snapshot backup of a replica node.
example: primary
responses:
'200':
description: Database snapshot backup request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "db-snapshot",
"target": "primary"
}' \
https://api.linode.com/v4/databases/postgresql/instances/123/backups/
- lang: CLI
source: >
linode-cli databases postgresql-backup-snapshot 123 \
--label db-snapshot \
--target primary
/databases/postgresql/instances/{instanceId}/backups/{backupId}:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed PostgreSQL Database backup.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed PostgreSQL Database Backup View
operationId: getDatabasesPostgreSQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-backup-view
x-linode-grant: read_only
description: |
Display information for a single backup for an accessible Managed PostgreSQL Database.
The Database must not be provisioning to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Returns a single backup for the Managed PostgreSQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseBackup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases postgresql-backup-view 123 456
delete:
tags:
- Databases
summary: Managed PostgreSQL Database Backup Delete
operationId: deleteDatabasePostgreSQLInstanceBackup
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-backup-delete
description: |
Delete a single backup for an accessible Managed PostgreSQL Database.
Requires `read_write` access to the Database.
The Database must not be provisioning to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to delete Database backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/databases/postgresql/instances/123/backups/456
- lang: CLI
source: >
linode-cli databases postgresql-backup-delete 123 456
/databases/postgresql/instances/{instanceId}/backups/{backupId}/restore:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Managed PostgreSQL Database backup.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed PostgreSQL Database Backup Restore
operationId: postDatabasesPostgreSQLInstanceBackupRestore
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-backup-restore
x-linode-grant: read_write
description: |
Restore a backup to a Managed PostgreSQL Database on your Account.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**: Restoring from a backup will erase all existing data on the database instance and replace it with backup data.
**Note**: Currently, restoring a backup after resetting Managed Database credentials results in a failed cluster. Please contact Customer Support if this occurs.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Request to restore backup successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/postgresql/instances/123/backups/456/restore
- lang: CLI
source: >
linode-cli databases postgresql-backup-restore 123 456
/databases/postgresql/instances/{instanceId}/credentials:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed PostgreSQL Database Credentials View
operationId: getDatabasesPostgreSQLInstanceCredentials
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-creds-view
x-linode-grant: read_only
description: |
Display the root username and password for an accessible Managed PostgreSQL Database.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Managed Database root username and password.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseCredentials'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/123/credentials/
- lang: CLI
source: >
linode-cli databases postgresql-creds-view 123
/databases/postgresql/instances/{instanceId}/credentials/reset:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed PostgreSQL Database Credentials Reset
operationId: postDatabasesPostgreSQLInstanceCredentialsReset
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-creds-reset
x-linode-grant: read_write
description: |
Reset the root password for a Managed PostgreSQL Database.
Requires `read_write` access to the Database.
A new root password is randomly generated and accessible with the **Managed PostgreSQL Database Credentials View** ([GET /databases/postgresql/instances/{instanceId}/credentials](/docs/api/databases/#managed-postgresql-database-credentials-view)) command.
Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes.
**Note**: Note that it may take several seconds for credentials to reset.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance credentials successfully reset.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/postgresql/instances/123/credentials/reset
- lang: CLI
source: >
linode-cli databases postgresql-creds-reset 123
/databases/postgresql/instances/{instanceId}/ssl:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
get:
tags:
- Databases
summary: Managed PostgreSQL Database SSL Certificate View
operationId: getDatabasesPostgreSQLInstanceSSL
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-ssl-cert
x-linode-grant: read_only
description: |
Display the SSL CA certificate for an accessible Managed PostgreSQL Database.
The Database must have an `active` status to perform this command.
security:
- personalAccessToken: []
- oauth:
- databases:read_only
responses:
'200':
description: Returns the SSL CA certificate of a single Managed PostgreSQL Database.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseSSL'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/databases/postgresql/instances/123/ssl
- lang: CLI
source: >
linode-cli databases postgresql-ssl-cert 123
/databases/postgresql/instances/{instanceId}/patch:
x-linode-cli-command: databases
parameters:
- name: instanceId
in: path
description: The ID of the Managed PostgreSQL Database.
required: true
schema:
type: integer
post:
tags:
- Databases
summary: Managed PostgreSQL Database Patch
operationId: postDatabasesPostgreSQLInstancePatch
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: postgresql-patch
x-linode-grant: read_write
description: |
Apply security patches and updates to the underlying operating system of the Managed PostgreSQL Database. This function runs during regular maintenance windows, which are configurable with the **Managed PostgreSQL Database Update** ([PUT /databases/postgresql/instances/{instanceId}](/docs/api/databases/#managed-postgresql-database-update)) command.
Requires `read_write` access to the Database.
The Database must have an `active` status to perform this command.
**Note**
* If your database cluster is configured with a single node, you will experience downtime during this maintenance. Consider upgrading to a high availability plan to avoid any downtime due to maintenance.
* **The database software is not updated automatically.** To upgrade to a new database engine version, consider deploying a new Managed Database with your preferred version. You can then migrate your databases from the original Managed Database cluster to the new one.
security:
- personalAccessToken: []
- oauth:
- databases:read_write
responses:
'200':
description: Managed Database instance patch request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST https://api.linode.com/v4/databases/postgresql/instances/123/patch
- lang: CLI
source: >
linode-cli databases postgresql-patch 123
/databases/types:
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed Database Types List
operationId: getDatabasesTypes
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: types
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display all Managed Database node types. The type and number of nodes determine the resources and price of a Managed Database instance.
Each Managed Database can have one node type. In the case of a high availabilty Database, all nodes are provisioned according to the chosen type.
responses:
'200':
description: Returns a paginated list of all Managed Database types.
content:
application/json:
x-linode-cli-nested-list: engines.mysql, engines.postgresql, engines.mongodb
x-linode-cli-use-schema:
type: object
properties:
id:
x-linode-cli-display: 1
label:
x-linode-cli-display: 2
_split:
x-linode-cli-display: 2.5
engines:
properties:
quantity:
x-linode-cli-display: 3
price:
properties:
hourly:
x-linode-cli-display: 4
monthly:
x-linode-cli-display: 5
schema:
allOf:
- $ref: '#/components/schemas/PaginationEnvelope'
- type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatabaseType'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/databases/types
- lang: CLI
source: >
linode-cli databases types
/databases/types/{typeId}:
parameters:
- name: typeId
in: path
description: The ID of the Managed Database type.
required: true
schema:
type: string
x-linode-cli-command: databases
get:
tags:
- Databases
summary: Managed Database Type View
operationId: getDatabasesType
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-cli-action: type-view
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
description: |
Display the details of a single Managed Database type. The type and number of nodes determine the resources and price of a Managed Database instance.
responses:
'200':
description: Returns a single Managed Database type.
content:
application/json:
x-linode-cli-nested-list: engines.mysql, engines.postgresql, engines.mongodb
x-linode-cli-use-schema:
type: object
properties:
id:
x-linode-cli-display: 1
label:
x-linode-cli-display: 2
_split:
x-linode-cli-display: 2.5
engines:
properties:
quantity:
x-linode-cli-display: 3
price:
properties:
hourly:
x-linode-cli-display: 4
monthly:
x-linode-cli-display: 5
schema:
$ref: '#/components/schemas/DatabaseType'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/databases/types/g6-nanode-1
- lang: CLI
source: >
linode-cli databases type-view g6-nanode-1
/domains:
x-linode-cli-command: domains
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Domains
summary: Domains List
description: >
This is a collection of Domains that you have registered in Linode's DNS
Manager. Linode is not a registrar, and in order for these to work you
must own the domains and point your registrar at Linode's nameservers.
operationId: getDomains
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- domains:read_only
responses:
'200':
description: A paginated list of Domains you have registered.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Domain'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/domains
- lang: CLI
source: >
linode-cli domains list
post:
x-linode-grant: add_domains
tags:
- Domains
summary: Domain Create
description: >
Adds a new Domain to Linode's DNS Manager. Linode is not a registrar, and
you must own the domain before adding it here. Be sure to point your
registrar to Linode's nameservers so that the records hosted here are
used.
operationId: createDomain
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- domains:read_write
requestBody:
description: Information about the domain you are registering.
required: true
content:
application/json:
schema:
required:
- domain
- type
allOf:
- $ref: '#/components/schemas/Domain'
responses:
'200':
description: |
Domain added successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"domain": "example.com",
"type": "master",
"soa_email": "admin@example.com",
"description": "Example Description",
"refresh_sec": 14400,
"retry_sec": 3600,
"expire_sec": 604800,
"ttl_sec": 3600,
"status": "active",
"master_ips": ["127.0.0.1","255.255.255.1","123.123.123.7"],
"axfr_ips": ["44.55.66.77"],
"group": "Example Display Group",
"tags": ["tag1","tag2"]
}' \
https://api.linode.com/v4/domains
- lang: CLI
source: >
linode-cli domains create \
--type master \
--domain example.org \
--soa_email admin@example.org
/domains/{domainId}:
x-linode-cli-command: domains
parameters:
- name: domainId
in: path
description: The ID of the Domain to access.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Domains
summary: Domain View
description: >
This is a single Domain that you have registered in Linode's DNS Manager.
Linode is not a registrar, and in order for this Domain record to work you
must own the domain and point your registrar at Linode's nameservers.
operationId: getDomain
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- domains:read_only
responses:
'200':
description: |
A single Domain in Linode's DNS Manager.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/domains/123
- lang: CLI
source: >
linode-cli domains view 123
put:
x-linode-grant: read_write
tags:
- Domains
summary: Domain Update
description: |
Update information about a Domain in Linode's DNS Manager.
operationId: updateDomain
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- domains:read_write
requestBody:
description: The Domain information to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
responses:
'200':
description: Domain update successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"domain": "example.com",
"type": "master",
"soa_email": "admin@example.com",
"description": "Example Description",
"refresh_sec": 14400,
"retry_sec": 3600,
"expire_sec": 604800,
"ttl_sec": 3600,
"status": "active",
"master_ips": ["127.0.0.1","255.255.255.1","123.123.123.7"],
"axfr_ips": ["44.55.66.77"],
"group": "Example Display Group",
"tags": ["tag1","tag2"]
}' \
https://api.linode.com/v4/domains/123
- lang: CLI
source: >
linode-cli domains update 1234 \
--retry_sec 7200 \
--ttl_sec 300
delete:
x-linode-grant: read_write
tags:
- Domains
summary: Domain Delete
description: >
Deletes a Domain from Linode's DNS Manager. The Domain will be removed
from Linode's nameservers shortly after this operation completes. This
also deletes all associated Domain Records.
operationId: deleteDomain
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- domains:read_write
responses:
'200':
description: Domain deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/domains/1234
- lang: CLI
source: >
linode-cli domains delete 1234
/domains/{domainId}/zone-file:
x-linode-cli-command: domains
parameters:
- name: domainId
in: path
description: ID of the Domain.
required: true
schema:
type: string
get:
x-linode-grant: read_only
tags:
- Domains
summary: Domain Zone File View
description: >
Returns the zone file for the last rendered zone for the specified domain.
operationId: getDomainZone
x-linode-cli-action: zone-file
security:
- personalAccessToken: []
- oauth:
- domains:read_only
responses:
'200':
description: |
An array containing the lines of the domain zone file.
content:
application/json:
schema:
properties:
zone_file:
type: array
items:
type: string
example:
- "; example.com [123]"
- "$TTL 864000"
- "@ IN SOA ns1.linode.com. user.example.com. 2021000066 14400 14400 1209600 86400"
- "@ NS ns1.linode.com."
- "@ NS ns2.linode.com."
- "@ NS ns3.linode.com."
- "@ NS ns4.linode.com."
- "@ NS ns5.linode.com."
description: |
The lines of the zone file for the last rendered zone for this domain.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/domains/123/zone-file
- lang: CLI
source: >
linode-cli domains zone-file 123
/domains/import:
x-linode-cli-command: domains
post:
x-linode-grant: read_write
x-linode-cli-command: domains
tags:
- Domains
summary: Domain Import
description: >
Imports a domain zone from a remote nameserver.
Your nameserver must allow zone transfers (AXFR) from the following IPs:
- 96.126.114.97
- 96.126.114.98
- 2600:3c00::5e
- 2600:3c00::5f
operationId: importDomain
x-linode-cli-action: import
security:
- personalAccessToken: []
- oauth:
- domains:read_write
requestBody:
description: Information about the Domain to import.
content:
application/json:
schema:
required:
- domain
- remote_nameserver
properties:
domain:
type: string
description: >
The domain to import.
example: example.com
remote_nameserver:
type: string
description: >
The remote nameserver that allows zone transfers (AXFR).
example: examplenameserver.com
responses:
'200':
description: |
A single Domain in Linode's DNS Manager.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"domain": "example.com",
"remote_nameserver": "examplenameserver.com"
}' \
https://api.linode.com/v4/domains/import
- lang: CLI
source: >
linode-cli domains import --domain example.com --remote_nameserver examplenameserver.com
/domains/{domainId}/clone:
x-linode-cli-command: domains
parameters:
- name: domainId
in: path
description: ID of the Domain to clone.
required: true
schema:
type: string
post:
x-linode-grant: read_write
tags:
- Domains
summary: Domain Clone
description: >
Clones a Domain and all associated DNS records from a Domain that is
registered in Linode's DNS manager.
operationId: cloneDomain
x-linode-cli-action: clone
security:
- personalAccessToken: []
- oauth:
- domains:read_write
requestBody:
description: Information about the Domain to clone.
required: true
content:
application/json:
schema:
required:
- domain
type: object
properties:
domain:
type: string
pattern: \A(\*\.)?([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)\Z
minLength: 1
maxLength: 255
description: >
The new domain for the clone. Domain labels cannot be longer than
63 characters and must conform to [RFC1035](https://tools.ietf.org/html/rfc1035).
Domains must be unique on Linode's platform, including across different Linode
accounts; there cannot be two Domains representing the same domain.
example: example.org
x-linode-filterable: true
responses:
'200':
description: |
A new Domain in Linode's DNS Manager, based on a cloned Domain.
content:
application/json:
schema:
$ref: '#/components/schemas/Domain'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"domain": "example.com"
}' \
https://api.linode.com/v4/domains/123/clone
- lang: CLI
source: >
linode-cli domains clone 123 --domain example.com
/domains/{domainId}/records:
x-linode-cli-command: domains
parameters:
- name: domainId
in: path
description: The ID of the Domain we are accessing Records for.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Domains
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
security:
- personalAccessToken: []
- oauth:
- domains:read_only
summary: Domain Records List
description: |
Returns a paginated list of Records configured on a Domain in Linode's
DNS Manager.
operationId: getDomainRecords
x-linode-cli-action: records-list
responses:
'200':
description: A list of Domain Records.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DomainRecord'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/domains/1234/records
- lang: CLI
source: >
linode-cli domains records-list 1234
post:
x-linode-grant: read_write
tags:
- Domains
security:
- personalAccessToken: []
- oauth:
- domains:read_write
summary: Domain Record Create
description: >
Adds a new Domain Record to the zonefile this Domain represents.
operationId: createDomainRecord
x-linode-cli-action: records-create
requestBody:
description: >
Information about the new Record to add.
required: true
content:
application/json:
schema:
required:
- type
allOf:
- $ref: '#/components/schemas/DomainRecord'
responses:
'200':
description: Domain Record created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/DomainRecord'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "A",
"name": "test",
"target": "12.34.56.78",
"priority": 50,
"weight": 50,
"port": 80,
"service": null,
"protocol": null,
"ttl_sec": 604800
}' \
https://api.linode.com/v4/domains/123/records
- lang: CLI
source: >
linode-cli domains records-create 123 \
--type A \
--name test \
--target 12.34.56.78 \
--priority 50 \
--weight 50 \
--port 80 \
--ttl_sec 604800
/domains/{domainId}/records/{recordId}:
x-linode-cli-command: domains
parameters:
- name: domainId
in: path
description: The ID of the Domain whose Record you are accessing.
required: true
schema:
type: integer
- name: recordId
in: path
description: The ID of the Record you are accessing.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- Domains
security:
- personalAccessToken: []
- oauth:
- domains:read_only
summary: Domain Record View
description: >
View a single Record on this Domain.
operationId: getDomainRecord
x-linode-cli-action: records-view
responses:
'200':
description: A Domain Record object.
content:
application/json:
schema:
$ref: '#/components/schemas/DomainRecord'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/domains/123/records/234
- lang: CLI
source: >
linode-cli domains records-view 123 234
put:
x-linode-grant: read_write
tags:
- Domains
security:
- personalAccessToken: []
- oauth:
- domains:read_write
summary: Domain Record Update
description: >
Updates a single Record on this Domain.
operationId: updateDomainRecord
x-linode-cli-action: records-update
requestBody:
description: The values to change.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DomainRecord'
responses:
'200':
description: Domain Record updated.
content:
application/json:
schema:
$ref: '#/components/schemas/DomainRecord'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"type": "A",
"name": "test",
"target": "12.34.56.78",
"priority": 50,
"weight": 50,
"port": 80,
"service": null,
"protocol": null,
"ttl_sec": 604800,
"tag": null
}' \
https://api.linode.com/v4/domains/123/records/234
- lang: CLI
source: >
linode-cli domains records-update 123 234 \
--type A \
--name test \
--target 12.34.56.78 \
--priority 50 \
--weight 50 \
--port 80 \
--ttl_sec 604800
delete:
x-linode-grant: read_write
tags:
- Domains
security:
- personalAccessToken: []
- oauth:
- domains:read_write
summary: Domain Record Delete
description: >
Deletes a Record on this Domain.
operationId: deleteDomainRecord
x-linode-cli-action: records-delete
responses:
'200':
description: Record deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/domains/123/records/234
- lang: CLI
source: >
linode-cli domains records-delete 123 234
/images:
x-linode-cli-command: images
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Images
summary: Images List
description: |
Returns a paginated list of Images.
* **Public** Images have IDs that begin with "linode/". These distribution images are generally available to
all users.
* **Private** Images have IDs that begin with "private/". These Images are Account-specific and only
accessible to Users with appropriate [Grants](/docs/api/account/#users-grants-view).
* To view only public Images, call this endpoint with or without authentication. To view private Images as well, call this endpoint with authentication.
x-linode-redoc-load-ids: true
operationId: getImages
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- images:read_only
responses:
'200':
description: A paginated list of Images.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Image'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: |
# Returns public Images only
curl https://api.linode.com/v4/images
# Returns private and public Images
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/images
- lang: CLI
source: >
linode-cli images list
post:
x-linode-grant: add_images
tags:
- Images
summary: Image Create
description: |
Captures a private gold-master Image from a Linode Disk.
operationId: createImage
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- images:read_write
- linodes:read_only
requestBody:
description: Information about the Image to create.
content:
application/json:
schema:
required:
- disk_id
properties:
disk_id:
type: integer
description: >
The ID of the Linode Disk that this Image will be
created from.
example: 42
label:
type: string
description: >
A short title of this Image. Defaults to the label of the
Disk it is being created from if not provided.
description:
type: string
description: >
A detailed description of this Image.
responses:
'200':
description: New private Image created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"disk_id": 123,
"label": "this_is_a_label",
"description": "A longer description of the image"
}' \
https://api.linode.com/v4/images
- lang: CLI
source: >
linode-cli images create \
--label this_is_a_label \
--description "A longer description \
of the image" \
--disk_id 123
/images/upload:
x-linode-cli-command: images
post:
x-linode-grant: add_images
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
tags:
- Images
summary: Image Upload
description: |
Initiates an Image upload.
This endpoint creates a new private Image object and returns it along
with the URL to which image data can be uploaded.
- Image data must be uploaded within 24 hours of creation or the
upload will be cancelled and the image deleted.
- Image uploads should be made as an HTTP PUT request to the URL returned in the `upload_to`
response parameter, with a `Content-type: application/octet-stream` header included in the
request. For example:
curl -v \
-H "Content-Type: application/octet-stream" \
--upload-file example.img.gz \
$UPLOAD_URL \
--progress-bar \
--output /dev/null
- Uploaded image data should be compressed in gzip (`.gz`) format. The uncompressed disk should be in raw
disk image (`.img`) format. A maximum compressed file size of 5GB is supported for upload at this time.
**Note:** To initiate and complete an Image upload in a single step, see our guide on how to [Upload an Image](/docs/products/tools/images/guides/upload-an-image/) using Cloud Manager or the Linode CLI `image-upload` plugin.
x-linode-cli-action: upload
security:
- personalAccessToken: []
- oauth:
- images:read_write
requestBody:
description: The uploaded Image details.
x-linode-cli-allowed-defaults:
- region
content:
application/json:
schema:
type: object
required:
- label
- region
properties:
region:
type: string
description: >
The region to upload to. Once uploaded, the Image can be used in any region.
example: eu-central
label:
type: string
description: Label for the uploaded Image.
example: my-image-label
description:
type: string
description: Description for the uploaded Image.
example: This is an example image in the docs.
responses:
'200':
description: Image Upload object including the upload URL and Image object.
content:
application/json:
schema:
type: object
properties:
upload_to:
type: string
description: The URL to upload the Image to.
x-linode-cli-display: 1
image:
$ref: '#/components/schemas/Image'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"description": "Optional details about the Image",
"label": "Example Image",
"region": "us-east"
}' \
https://api.linode.com/v4/images/upload
- lang: CLI
source: |
# Upload the Image file in a single step
linode-cli image-upload \
--description "Optional details about the Image" \
--label "Example Image" \
--region us-east \
/path/to/image-file.img.gz
# Returns the upload_to URL
linode-cli images upload \
--description "Optional details about the Image" \
--label "Example Image" \
--region us-east
/images/{imageId}:
x-linode-cli-command: images
parameters:
- name: imageId
in: path
description: ID of the Image to look up.
required: true
schema:
type: string
get:
tags:
- Images
summary: Image View
description: |
Get information about a single Image.
* **Public** Images have IDs that begin with "linode/". These distribution images are generally available to
all users.
* **Private** Images have IDs that begin with "private/". These Images are Account-specific and only
accessible to Users with appropriate [Grants](/docs/api/account/#users-grants-view).
* To view a public Image, call this endpoint with or without authentication. To view a private Image, call this endpoint with authentication.
operationId: getImage
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- images:read_only
responses:
'200':
description: A single Image object.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: |
# Public Image
curl https://api.linode.com/v4/images/linode/debian11
# Private Image
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/images/private/12345
- lang: CLI
source: >
linode-cli images view linode/debian9
put:
x-linode-grant: read_write
tags:
- Images
summary: Image Update
description: >
Updates a private Image that you have permission to
`read_write`.
operationId: updateImage
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- images:read_write
requestBody:
description: >
The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
responses:
'200':
description: The updated image.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "My gold-master image",
"description": "The detailed description of my Image."
}' \
https://api.linode.com/v4/images/private/12345
- lang: CLI
source: >
linode-cli images update private/12345 \
--label "My gold-master image" \
--description "The detailed description \
of my Image."
delete:
x-linode-grant: read_write
tags:
- Images
summary: Image Delete
description: |
Deletes a private Image you have permission to `read_write`.
**Deleting an Image is a destructive action and cannot be undone.**
operationId: deleteImage
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- images:read_write
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/images/private/12345
- lang: CLI
source: >
linode-cli images delete 12345
/linode/instances:
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: Linodes List
description: >
Returns a paginated list of Linodes you have permission to view.
tags:
- Linode Instances
operationId: getLinodeInstances
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns an array of all Linodes on your Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Linode'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances
- lang: CLI
source: >
linode-cli linodes list
post:
x-linode-charge: true
x-linode-grant: add_linodes
summary: Linode Create
description: |
Creates a Linode Instance on your Account. In order for this
request to complete successfully, your User must have the `add_linodes` grant. Creating a
new Linode will incur a charge on your Account.
Linodes can be created using one of the available Types. See
Types List ([GET /linode/types](/docs/api/linode-types/#types-list)) to get more
information about each Type's specs and cost.
Linodes can be created in any one of our available Regions, which are accessible from the
Regions List ([GET /regions](/docs/api/regions/#regions-list)) endpoint.
In an effort to fight spam, Linode restricts outbound connections on ports 25, 465, and 587
on all Linodes for new accounts created after November 5th, 2019. For more information,
see [Sending Email on Linode](/docs/email/running-a-mail-server/#sending-email-on-linode).
Linodes can be created in a number of ways:
* Using a Linode Public Image distribution or a Private Image you created based on another Linode.
* Access the Images List ([GET /images](/docs/api/images/#images-list)) endpoint with authentication to view
all available Images.
* The Linode will be `running` after it completes `provisioning`.
* A default config with two Disks, one being a 512 swap disk, is created.
* `swap_size` can be used to customize the swap disk size.
* Requires a `root_pass` be supplied to use for the root User's Account.
* It is recommended to supply SSH keys for the root User using the `authorized_keys` field.
* You may also supply a list of usernames via the `authorized_users` field.
* These users must have an SSH Key associated with your Profile first. See SSH Key Add ([POST /profile/sshkeys](/docs/api/profile/#ssh-key-add)) for more information.
* Using a StackScript.
* See StackScripts List ([GET /linode/stackscripts](/docs/api/stackscripts/#stackscripts-list)) for
a list of available StackScripts.
* The Linode will be `running` after it completes `provisioning`.
* Requires a compatible Image to be supplied.
* See StackScript View ([GET /linode/stackscript/{stackscriptId}](/docs/api/stackscripts/#stackscript-view)) for compatible Images.
* Requires a `root_pass` be supplied to use for the root User's Account.
* It is recommended to supply SSH keys for the root User using the `authorized_keys` field.
* You may also supply a list of usernames via the `authorized_users` field.
* These users must have an SSH Key associated with your Profile first. See SSH Key Add ([POST /profile/sshkeys](/docs/api/profile/#ssh-key-add)) for more information.
* Using one of your other Linode's backups.
* You must create a Linode large enough to accommodate the Backup's size.
* The Disks and Config will match that of the Linode that was backed up.
* The `root_pass` will match that of the Linode that was backed up.
* Attached to a private VLAN.
* Review the `interfaces` property of the [Request Body Schema](/docs/api/linode-instances/#linode-create__request-body-schema) for details.
* For more information, see our guide on [Getting Started with VLANs](/docs/guides/getting-started-with-vlans/).
* Create an empty Linode.
* The Linode will remain `offline` and must be manually started.
* See Linode Boot ([POST /linode/instances/{linodeId}/boot](/docs/api/linode-instances/#linode-boot)).
* Disks and Configs must be created manually.
* This is only recommended for advanced use cases.
**Important**: You must be an unrestricted User in order to add or modify
tags on Linodes.
tags:
- Linode Instances
operationId: createLinodeInstance
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The requested initial state of a new Linode.
required: true
x-linode-cli-allowed-defaults:
- region
- image
- type
content:
application/json:
schema:
required:
- type
- region
type: object
allOf:
- $ref: '#/components/schemas/LinodeRequest'
- properties:
backup_id:
type: integer
example: 1234
description: |
A Backup ID from another Linode's available backups. Your User must have
`read_write` access to that Linode, the Backup must have a `status` of
`successful`, and the Linode must be deployed to the same `region` as the Backup.
See [GET /linode/instances/{linodeId}/backups](/docs/api/linode-instances/#backups-list)
for a Linode's available backups.
This field and the `image` field are mutually exclusive.
backups_enabled:
type: boolean
description: |
If this field is set to `true`, the created Linode will automatically be
enrolled in the Linode Backup service. This will incur an additional charge.
The cost for the Backup service is dependent on the Type of Linode deployed.
This option is always treated as `true` if the account-wide `backups_enabled`
setting is `true`. See [account settings](/docs/api/account/#account-settings-view)
for more information.
Backup pricing is included in the response from [/linodes/types](/docs/api/linode-types/#types-list)
swap_size:
type: integer
example: 512
description: >
When deploying from an Image, this field is optional, otherwise it is ignored.
This is used to set the swap disk size for the newly-created Linode.
default: 512
type:
type: string
description: >
The [Linode Type](/docs/api/linode-types/#types-list) of the Linode
you are creating.
example: g6-standard-2
region:
type: string
description: >
The [Region](/docs/api/regions/#regions-list) where the Linode
will be located.
example: us-east
label:
$ref: '#/components/schemas/Linode/properties/label'
tags:
$ref: '#/components/schemas/Linode/properties/tags'
group:
$ref: '#/components/schemas/Linode/properties/group'
private_ip:
type: boolean
description: >
If true, the created Linode will have private networking enabled and assigned a private IPv4 address.
example: true
interfaces:
$ref: '#/components/schemas/LinodeConfigInterfaces'
responses:
'200':
description: >
A new Linode is being created.
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"backup_id": 1234,
"backups_enabled": true,
"swap_size": 512,
"image": "linode/debian9",
"root_pass": "aComplexP@ssword",
"stackscript_id": 10079,
"stackscript_data": {
"gh_username": "linode"
},
"interfaces": [
{
"purpose": "public",
"label": "",
"ipam_address": ""
},
{
"purpose": "vlan",
"label": "vlan-1",
"ipam_address": "10.0.0.1/24"
}
],
"authorized_keys": [
"ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
],
"authorized_users": [
"myUser",
"secondaryUser"
],
"booted": true,
"label": "linode123",
"type": "g6-standard-2",
"region": "us-east",
"group": "Linode-Group"
}' \
https://api.linode.com/v4/linode/instances
- lang: CLI
source: >
linode-cli linodes create \
--label linode123 \
--root_pass aComplex@Password \
--booted true \
--stackscript_id 10079 \
--stackscript_data '{"gh_username": "linode"}' \
--region us-east \
--type g6-standard-2 \
--authorized_keys "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
--authorized_users "myUser"
--authorized_users "secondaryUser"
/linode/instances/{linodeId}:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Linode View
description: Get a specific Linode by ID.
operationId: getLinodeInstance
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns a single Linode object.
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
links:
boot:
$ref: '#/components/links/bootLinode'
reboot:
$ref: '#/components/links/rebootLinode'
shutdown:
$ref: '#/components/links/shutdownLinode'
update:
$ref: '#/components/links/updateLinode'
delete:
$ref: '#/components/links/deleteLinode'
rebuild:
$ref: '#/components/links/rebuildLinode'
mutate:
$ref: '#/components/links/mutateLinode'
resize:
$ref: '#/components/links/resizeLinode'
rescue:
$ref: '#/components/links/rescueLinode'
clone:
$ref: '#/components/links/cloneLinode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123
- lang: CLI
source: >
linode-cli linodes view 123
put:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Linode Update
description: >
Updates a Linode that you have permission to `read_write`.
**Important**: You must be an unrestricted User in order to add or modify
tags on Linodes.
operationId: updateLinodeInstance
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: >
Any field that is not marked as `readOnly` may be updated. Fields that are marked
`readOnly` will be ignored. If any updated field fails to pass validation, the Linode will
not be updated.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
responses:
'200':
description: The updated Linode.
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "linode123",
"group": "Linode-Group",
"alerts": {
"cpu": 180,
"network_in": 10,
"network_out": 10,
"transfer_quota": 80,
"io": 10000
},
"backups": {
"schedule": {
"day": "Saturday",
"window": "W22"
}
}
}' \
https://api.linode.com/v4/linode/instances/123
- lang: CLI
source: >
linode-cli linodes update 7833080 \
--label linode123 \
--backups.schedule.day "Saturday" \
--backups.schedule.window "W22" \
--alerts.cpu 180 \
--alerts.network_in 10 \
--alerts.network_out 10 \
--alerts.transfer_quota 80 \
--alerts.io 10000
delete:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Linode Delete
description: |
Deletes a Linode you have permission to `read_write`.
**Deleting a Linode is a destructive action and cannot be undone.**
Additionally, deleting a Linode:
* Gives up any IP addresses the Linode was assigned.
* Deletes all Disks, Backups, Configs, etc.
* Stops billing for the Linode and its associated services. You will be billed for time used
within the billing period the Linode was active.
Linodes that are in the process of [cloning](/docs/api/linode-instances/#linode-clone) or [backup restoration](/docs/api/linode-instances/#backup-restore) cannot be deleted.
operationId: deleteLinodeInstance
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/linode/instances/123
- lang: CLI
source: >
linode-cli linodes delete 123
/linode/instances/{linodeId}/backups:
parameters:
- name: linodeId
in: path
description: The ID of the Linode the backups belong to.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
summary: Backups List
description: >
Returns information about this Linode's available backups.
tags:
- Linode Instances
operationId: getBackups
x-linode-cli-action: backups-list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: A collection of the specified Linode's available backups.
content:
application/json:
x-linode-cli-rows:
- automatic
- snapshot.current
- snapshot.in_progress
x-linode-cli-use-schema:
$ref: '#/components/schemas/Backup'
schema:
type: object
properties:
automatic:
type: array
items:
allOf:
- $ref: '#/components/schemas/Backup'
- properties:
type:
type: string
example: automatic
snapshot:
type: object
properties:
in_progress:
$ref: '#/components/schemas/Backup'
current:
$ref: '#/components/schemas/Backup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/backups
- lang: CLI
source: >
linode-cli linodes backups-list 123
post:
x-linode-grant: read_write
summary: Snapshot Create
description: |
Creates a snapshot Backup of a Linode.
**Important:** If you already have a snapshot of this Linode, this is a destructive
action. The previous snapshot will be deleted.
tags:
- Linode Instances
operationId: createSnapshot
x-linode-cli-action: snapshot
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
required: true
content:
application/json:
schema:
required:
- label
type: object
properties:
label:
type: string
minLength: 1
maxLength: 255
description: The label for the new snapshot.
example: SnapshotLabel
responses:
'200':
description: Snapshot request successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Backup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "MyNewSnapshot"
}' \
https://api.linode.com/v4/linode/instances/123/backups
- lang: CLI
source: >
linode-cli linodes snapshot 123
/linode/instances/{linodeId}/backups/cancel:
parameters:
- name: linodeId
in: path
description: The ID of the Linode to cancel backup service for.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Backups Cancel
description: >
Cancels the Backup service on the given Linode. Deletes all of this Linode's
existing backups forever.
tags:
- Linode Instances
operationId: cancelBackups
x-linode-cli-action: backups-cancel
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Backup service was cancelled for the specified Linode.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/backups/cancel
- lang: CLI
source: >
linode-cli linodes backups-cancel 123
/linode/instances/{linodeId}/backups/enable:
parameters:
- name: linodeId
in: path
description: The ID of the Linode to enable backup service for.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Backups Enable
description: >
Enables backups for the specified Linode.
tags:
- Linode Instances
operationId: enableBackups
x-linode-cli-action: backups-enable
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Backup service was enabled.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/backups/enable
- lang: CLI
source: >
linode-cli linodes backups-enable 123
/linode/instances/{linodeId}/backups/{backupId}:
parameters:
- name: linodeId
in: path
description: The ID of the Linode the Backup belongs to.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Backup to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
summary: Backup View
description: >
Returns information about a Backup.
tags:
- Linode Instances
operationId: getBackup
x-linode-cli-action: backup-view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: A single Backup.
content:
application/json:
schema:
$ref: '#/components/schemas/Backup'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/backups/123456
- lang: CLI
source: >
linode-cli linodes backup-view 123 123456
/linode/instances/{linodeId}/backups/{backupId}/restore:
parameters:
- name: linodeId
in: path
description: The ID of the Linode that the Backup belongs to.
required: true
schema:
type: integer
- name: backupId
in: path
description: The ID of the Backup to restore.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Backup Restore
description: >
Restores a Linode's Backup to the specified Linode.
tags:
- Linode Instances
operationId: restoreBackup
x-linode-cli-action: backup-restore
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Parameters to provide when restoring the Backup.
required: true
content:
application/json:
schema:
type: object
required:
- linode_id
properties:
linode_id:
type: integer
description: >
The ID of the Linode to restore a Backup to.
example: 234
overwrite:
type: boolean
description: |
If True, deletes all Disks and Configs on the target Linode
before restoring.
If False, and the Disk image size is larger than the available
space on the Linode, an error message indicating insufficient
space is returned.
example: true
responses:
'200':
description: Restore from Backup was initiated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 234,
"overwrite": true
}' \
https://api.linode.com/v4/linode/instances/123/backups/123456/restore
- lang: CLI
source: >
linode-cli linodes backup-restore 123 123456 \
--linode_id 234 \
--overwrite true
/linode/instances/{linodeId}/boot:
parameters:
- name: linodeId
in: path
description: The ID of the Linode to boot.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Boot
description: |
Boots a Linode you have permission to modify. If no parameters are given, a Config profile
will be chosen for this boot based on the following criteria:
* If there is only one Config profile for this Linode, it will be used.
* If there is more than one Config profile, the last booted config will be used.
* If there is more than one Config profile and none were the last to be booted (because the
Linode was never booted or the last booted config was deleted) an error will be returned.
tags:
- Linode Instances
operationId: bootLinodeInstance
x-linode-cli-action: boot
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Optional configuration to boot into (see above).
required: false
content:
application/json:
schema:
type: object
properties:
config_id:
type: integer
description: >
The Linode Config ID to boot into.
example: null
responses:
'200':
description: Boot started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/boot
- lang: CLI
source: >
linode-cli linodes boot 123
/linode/instances/{linodeId}/clone:
parameters:
- name: linodeId
in: path
description: ID of the Linode to clone.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-charge: true
x-linode-grant: add_linodes
summary: Linode Clone
description: |
You can clone your Linode's existing Disks or Configuration profiles to
another Linode on your Account. In order for this request to complete
successfully, your User must have the `add_linodes` grant. Cloning to a
new Linode will incur a charge on your Account.
If cloning to an existing Linode, any actions currently running or
queued must be completed first before you can clone to it.
Up to five clone operations from any given source Linode can be run concurrently.
If more concurrent clones are attempted, an HTTP 400 error will be
returned by this endpoint.
Any [tags](/docs/api/tags/#tags-list) existing on the source Linode will be cloned to the target Linode.
tags:
- Linode Instances
operationId: cloneLinodeInstance
x-linode-cli-action: clone
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The requested state your Linode will be cloned into.
required: true
x-linode-cli-allowed-defaults:
- region
- type
content:
application/json:
schema:
type: object
properties:
region:
type: string
description: >
This is the Region where the Linode will be deployed.
To view all available Regions you can deploy to see
[/regions](/docs/api/regions/#regions-list).
* Region can only be provided and is required when cloning to a new Linode.
example: us-east
type:
type: string
description: |
A Linode's Type determines what resources are available to
it, including disk space, memory, and virtual cpus. The
amounts available to a specific Linode are returned as
`specs` on the Linode object.
To view all available Linode Types you can deploy with
see [/linode/types](/docs/api/linode-types/#types-list).
* Type can only be provided and is required when cloning to a new Linode.
example: g6-standard-2
linode_id:
type: integer
description: >
If an existing Linode is the target for the clone,
the ID of that Linode. The existing Linode must have enough
resources to accept the clone.
example: 124
label:
type: string
minLength: 3
maxLength: 64
description: >
The label to assign this Linode when cloning to a new Linode.
* Can only be provided when cloning to a new Linode.
* Defaults to "linode".
example: cloned-linode
group:
deprecated: true
type: string
description: >
A label used to group Linodes for display. Linodes are not
required to have a group.
example: Linode-Group
backups_enabled:
type: boolean
description: |
If this field is set to `true`, the created Linode will
automatically be enrolled in the Linode Backup service. This
will incur an additional charge. Pricing is included in the
response from
[/linodes/types](/docs/api/linode-types/#types-list).
* Can only be included when cloning to a new Linode.
example: true
disks:
type: array
description: >
An array of disk IDs.
* If the `disks` parameter **is not provided**, then **no extra disks
will be cloned** from the source Linode. All disks associated
with the configuration profiles specified by the `configs`
parameter will still be cloned.
* **If an empty array is provided** for the `disks` parameter, then **no extra disks
will be cloned** from the source Linode. All disks associated
with the configuration profiles specified by the `configs`
parameter will still be cloned.
* **If a non-empty array is provided** for the `disks` parameter, then **the disks
specified in the array will be cloned** from the source Linode, in addition to
any disks associated with the configuration profiles specified by the `configs`
parameter.
items:
type: integer
example: 25674
configs:
type: array
description: >
An array of configuration profile IDs.
* If the `configs` parameter **is not provided**, then **all configuration profiles and their associated disks
will be cloned** from the source Linode. Any disks specified by the `disks`
parameter will also be cloned.
* **If an empty array is provided** for the `configs` parameter, then **no
configuration profiles (nor their associated disks) will be cloned** from
the source Linode. Any disks specified by the `disks`
parameter will still be cloned.
* **If a non-empty array is provided** for the `configs` parameter, then **the configuration profiles
specified in the array (and their associated disks) will be cloned** from the source Linode.
Any disks specified by the `disks` parameter will also be cloned.
items:
type: integer
example: 23456
responses:
'200':
description: Clone started.
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"type": "g6-standard-2",
"linode_id": 124,
"label": "cloned-linode",
"group": "Linode-Group",
"backups_enabled": true,
"disks": [25674],
"configs": [23456]
}' \
https://api.linode.com/v4/linode/instances/123/clone
- lang: CLI
source: >
linode-cli linodes clone 123 \
--linode_id 124 \
--region us-east \
--type g6-standard-2 \
--label cloned-linode \
--backups_enabled true \
--disks 25674 \
--configs 23456
/linode/instances/{linodeId}/configs:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up Configuration profiles for.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Linode Instances
summary: Configuration Profiles List
description: |
Lists Configuration profiles associated with a Linode.
operationId: getLinodeConfigs
x-linode-cli-action: configs-list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: >
Returns an array of Configuration profiles associated with this Linode.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LinodeConfig'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/configs
- lang: CLI
source: >
linode-cli linodes configs-list 123
post:
tags:
- Linode Instances
summary: Configuration Profile Create
description: >
Adds a new Configuration profile to a Linode.
operationId: addLinodeConfig
x-linode-cli-action: config-create
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: >
The parameters to set when creating the Configuration profile.
This determines which kernel, devices, how much memory, etc. a Linode boots with.
required: true
content:
application/json:
schema:
required:
- label
- devices
allOf:
- $ref: '#/components/schemas/LinodeConfig'
responses:
'200':
description: |
A Configuration profile was created.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"kernel": "linode/latest-64bit",
"comments": "This is my main Config",
"memory_limit": 2048,
"run_level": "default",
"virt_mode": "paravirt",
"interfaces": [
{
"purpose": "public",
"label": "",
"ipam_address": ""
},
{
"purpose": "vlan",
"label": "vlan-1",
"ipam_address": "10.0.0.1/24"
}
],
"helpers": {
"updatedb_disabled": true,
"distro": true,
"modules_dep": true,
"network": true,
"devtmpfs_automount": false
},
"label": "My Config",
"devices": {
"sda": {
"disk_id": 123456,
"volume_id": null
},
"sdb": {
"disk_id": 123457,
"volume_id": null
}
}
}' \
https://api.linode.com/v4/linode/instances/123/configs
- lang: CLI
source: >
linode-cli linodes config-create 7590910 \
--label "My Config" \
--devices.sda.disk_id 123456 \
--devices.sdb.disk_id 123457
/linode/instances/{linodeId}/configs/{configId}:
parameters:
- name: linodeId
in: path
description: The ID of the Linode whose Configuration profile to look up.
required: true
schema:
type: integer
- name: configId
in: path
description: The ID of the Configuration profile to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
tags:
- Linode Instances
x-linode-grant: read_only
summary: Configuration Profile View
description: >
Returns information about a specific Configuration profile.
operationId: getLinodeConfig
x-linode-cli-action: config-view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: A Configuration profile object.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/configs/23456
- lang: CLI
source: >
linode-cli linodes config-view 123 23456
put:
x-linode-grant: read_write
summary: Configuration Profile Update
description: >
Updates a Configuration profile.
tags:
- Linode Instances
operationId: updateLinodeConfig
x-linode-cli-action: config-update
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The Configuration profile parameters to modify.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeConfig'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"kernel": "linode/latest-64bit",
"comments": "This is my main Config",
"memory_limit": 2048,
"run_level": "default",
"virt_mode": "paravirt",
"interfaces": [
{
"purpose": "public",
"label": "",
"ipam_address": ""
},
{
"purpose": "vlan",
"label": "vlan-1",
"ipam_address": "10.0.0.1/24"
}
],
"helpers": {
"updatedb_disabled": true,
"distro": true,
"modules_dep": true,
"network": true,
"devtmpfs_automount": false
},
"label": "My Config",
"devices": {
"sda": {
"disk_id": 123456,
"volume_id": null
},
"sdb": {
"disk_id": 123457,
"volume_id": null
}
}
}' \
https://api.linode.com/v4/linode/instances/123/configs/23456
- lang: CLI
source: >
linode-cli linodes config-update 123 23456 \
--kernel "linode/latest-64bit" \
--comments "This is my main Config" \
--memory_limit 2048 \
--run_level default \
--virt_mode paravirt \
--helpers.updatedb_disabled true \
--helpers.distro true \
--helpers.modules_dep true \
--helpers.network true \
--helpers.devtmpfs_automount false \
--label "My Config" \
--devices.sda.disk_id 123456 \
--devices.sdb.disk_id 123457
responses:
'200':
description: Configuration profile successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeConfig'
default:
$ref: '#/components/responses/ErrorResponse'
delete:
summary: Configuration Profile Delete
description: >
Deletes the specified Configuration profile from the specified Linode.
x-linode-grant: read_write
tags:
- Linode Instances
operationId: deleteLinodeConfig
x-linode-cli-action: config-delete
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: >
Configuration profile successfully deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/linode/instances/123/configs/23456
- lang: CLI
source: >
linode-cli linodes config-delete 123 23456
/linode/instances/{linodeId}/disks:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Linode Instances
summary: Disks List
description: >
View Disk information for Disks associated with this Linode.
operationId: getLinodeDisks
x-linode-cli-action: disks-list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns a paginated list of disks associated with this Linode.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Disk'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/disks
- lang: CLI
source: >
linode-cli linodes disks-list 123
post:
tags:
- Linode Instances
summary: Disk Create
description: |
Adds a new Disk to a Linode.
* You can optionally create a Disk from an Image or an Empty Disk if no Image is provided with a request.
* When creating an Empty Disk, providing a `label` is required.
* If no `label` is provided, an `image` is required instead.
* When creating a Disk from an Image, `root_pass` is required.
* The default filesystem for new Disks is `ext4`. If creating a Disk from an Image, the filesystem
of the Image is used unless otherwise specified.
* When deploying a StackScript on a Disk:
* See StackScripts List ([GET /linode/stackscripts](/docs/api/stackscripts/#stackscripts-list)) for
a list of available StackScripts.
* Requires a compatible Image to be supplied.
* See StackScript View ([GET /linode/stackscript/{stackscriptId}](/docs/api/stackscripts/#stackscript-view)) for compatible Images.
* It is recommended to supply SSH keys for the root User using the `authorized_keys` field.
* You may also supply a list of usernames via the `authorized_users` field.
* These users must have an SSH Key associated with their Profiles first. See SSH Key Add ([POST /profile/sshkeys](/docs/api/profile/#ssh-key-add)) for more information.
operationId: addLinodeDisk
x-linode-cli-action: disk-create
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: >
The parameters to set when creating the Disk.
required: true
content:
application/json:
schema:
required:
- size
allOf:
- $ref: '#/components/schemas/DiskRequest'
responses:
'200':
description: Disk created.
content:
application/json:
schema:
$ref: '#/components/schemas/Disk'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "Debian 9 Disk",
"image": "linode/debian9",
"size": 1300,
"authorized_keys": [
"ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
],
"authorized_users": [
"myUser",
"secondaryUser"
],
"root_pass": "aComplexP@ssword",
"stackscript_id": 10079,
"stackscript_data": {
"gh_username": "linode"
}
}' \
https://api.linode.com/v4/linode/instances/123/disks
- lang: CLI
source: >
linode-cli linodes disk-create 123 \
--size 1300 \
--authorized_keys "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" \
--authorized_users "myUser" \
--authorized_users "secondaryUser" \
--root_pass aComplex@Password \
--image "linode/debian9" \
--stackscript_id 10079 \
--stackscript_data '{"gh_username": "linode"}'
/linode/instances/{linodeId}/disks/{diskId}:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: diskId
in: path
description: ID of the Disk to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Disk View
description: >
View Disk information for a Disk associated with this Linode.
operationId: getLinodeDisk
x-linode-cli-action: disk-view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns a single Disk object.
content:
application/json:
schema:
$ref: '#/components/schemas/Disk'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/disks/25674
- lang: CLI
source: >
linode-cli linodes disk-view 123 25674
put:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Disk Update
description: >
Updates a Disk that you have permission to `read_write`.
operationId: updateDisk
x-linode-cli-action: disk-update
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: >
Updates the parameters of a single Disk.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Disk'
responses:
'200':
description: The updated Disk.
content:
application/json:
schema:
$ref: '#/components/schemas/Disk'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "Debian 9 Disk"
}' \
https://api.linode.com/v4/linode/instances/123/disks/25674
- lang: CLI
source: >
linode-cli linodes disk-update 123 25674 \
--label "Debian 9 Disk"
delete:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Disk Delete
description: |
Deletes a Disk you have permission to `read_write`.
**Deleting a Disk is a destructive action and cannot be undone.**
operationId: deleteDisk
x-linode-cli-action: disk-delete
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/linode/instances/123/disks/25674
- lang: CLI
source: >
linode-cli linodes disk-delete 123 24674
/linode/instances/{linodeId}/disks/{diskId}/clone:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: diskId
in: path
description: ID of the Disk to clone.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Disk Clone
description: >
Copies a disk, byte-for-byte, into a new Disk belonging to the same Linode.
The Linode must have enough storage space available to accept a new Disk
of the same size as this one or this operation will fail.
operationId: cloneLinodeDisk
x-linode-cli-action: disk-clone
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Disk clone initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/Disk'
default:
$ref: '#/components/responses/ErrorResponse'
/linode/instances/{linodeId}/disks/{diskId}/password:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: diskId
in: path
description: ID of the Disk to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Disk Root Password Reset
description: >
Resets the password of a Disk you have permission to `read_write`.
operationId: resetDiskPassword
x-linode-cli-action: disk-reset-password
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The new password.
required: true
content:
application/json:
schema:
required:
- password
properties:
password:
type: string
description: >
The new root password for the OS installed on this Disk.
The password must meet the complexity strength validation requirements for a strong password.
example: another@complex^Password123
responses:
'200':
description: Returns a single Disk object.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"password": "another@complex^Password123"
}' \
https://api.linode.com/v4/linode/instances/123/disks/25674/password
- lang: CLI
source: >
linode-cli linodes disk-reset-password \
123 25674 \
--password aComplex@Password
/linode/instances/{linodeId}/disks/{diskId}/resize:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: diskId
in: path
description: ID of the Disk to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
tags:
- Linode Instances
summary: Disk Resize
description: |
Resizes a Disk you have permission to `read_write`.
The Disk must not be in use. If the Disk is in use, the request will
succeed but the resize will ultimately fail. For a request to succeed,
the Linode must be shut down prior to resizing the Disk, or the Disk
must not be assigned to the Linode's active Configuration Profile.
If you are resizing the Disk to a smaller size, it cannot be made smaller
than what is required by the total size of the files current on the Disk.
operationId: resizeDisk
x-linode-cli-action: disk-resize
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The new size of the Disk.
required: true
content:
application/json:
schema:
required:
- size
properties:
size:
type: integer
description: >
The desired size, in MB, of the disk.
minimum: 1
example: 2048
responses:
'200':
description: Resize started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"size": 2048
}' \
https://api.linode.com/v4/linode/instances/123/disks/25674/resize
- lang: CLI
source: >
linode-cli linodes disk-resize 123 25674 \
--size 2048
/linode/instances/{linodeId}/firewalls:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Linode Instances
summary: Firewalls List
description: >
View Firewall information for Firewalls associated with this Linode.
operationId: getLinodeFirewalls
x-linode-cli-action: firewalls-list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns a paginated list of Firewalls associated with this Linode.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Firewall'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/firewalls
- lang: CLI
source: >
linode-cli linodes firewalls-list 123
/linode/instances/{linodeId}/ips:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Networking Information List
description: >
Returns networking information for a single Linode.
operationId: getLinodeIPs
x-linode-cli-action: ips-list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Requested Linode's networking configuration.
content:
application/json:
schema:
properties:
ipv4:
type: object
description: >
Information about this Linode's IPv4 addresses.
readOnly: true
properties:
public:
type: array
items:
$ref: '#/components/schemas/IPAddress'
description: >
A list of public IP Address objects belonging to this Linode.
readOnly: true
private:
type: array
items:
$ref: '#/components/schemas/IPAddressPrivate'
description: >
A list of private IP Address objects belonging to this Linode.
readOnly: true
shared:
type: array
readOnly: true
items:
$ref: '#/components/schemas/IPAddress'
description: >
A list of shared IP Address objects assigned to this Linode.
reserved:
type: array
readOnly: true
items:
$ref: '#/components/schemas/IPAddress'
description: >
A list of reserved IP Address objects belonging to this Linode.
ipv6:
type: object
description: >
Information about this Linode's IPv6 addresses.
readOnly: true
properties:
link_local:
$ref: '#/components/schemas/IPAddressV6LinkLocal'
slaac:
$ref: '#/components/schemas/IPAddressV6Slaac'
global:
$ref: '#/components/schemas/IPv6Pool'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
https://api.linode.com/v4/linode/instances/123/ips
- lang: CLI
source: >
linode-cli linodes 123 ips-list
post:
x-linode-grant: read_write
tags:
- Linode Instances
summary: IPv4 Address Allocate
description: >
Allocates a public or private IPv4 address to a Linode.
Public IP Addresses, after the one included with each Linode,
incur an additional monthly charge. If you need an additional public
IP Address you must request one - please
[open a support ticket](/docs/api/support/#support-ticket-open).
You may not add more than one private IPv4 address to a single Linode.
operationId: addLinodeIP
x-linode-cli-action: ip-add
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Information about the address you are creating.
required: true
content:
application/json:
schema:
required:
- type
- public
properties:
type:
type: string
enum:
- ipv4
description: >
The type of address you are allocating. Only IPv4 addresses
may be allocated through this endpoint.
example: ipv4
public:
type: boolean
description: >
Whether to create a public or private IPv4 address.
example: true
responses:
'200':
description: IP address was successfully allocated.
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "ipv4",
"public": true
}' \
https://api.linode.com/v4/linode/instances/123/ips
- lang: CLI
source: >
linode-cli linodes ip-add 123 \
--type ipv4 \
--public true
/linode/instances/{linodeId}/ips/{address}:
parameters:
- name: linodeId
in: path
description: The ID of the Linode to look up.
required: true
schema:
type: integer
- name: address
in: path
description: The IP address to look up.
required: true
schema:
type: string
format: ip
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: IP Address View
description: >
View information about the specified IP address associated
with the specified Linode.
operationId: getLinodeIP
x-linode-cli-action: ip-view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: A single IP address.
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
https://api.linode.com/v4/linode/instances/123/ips/97.107.143.141
- lang: CLI
source: >
linode-cli linodes ip-view 123 97.107.143.141
put:
x-linode-grant: read_write
tags:
- Linode Instances
summary: IP Address Update
description: >
Updates a particular IP Address associated with this Linode.
Only allows setting/resetting reverse DNS.
operationId: updateLinodeIP
x-linode-cli-action: ip-update
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The information to update for the IP address.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/IPAddress'
responses:
'200':
description: The updated IP address record.
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"rdns": "test.example.org"
}' \
https://api.linode.com/v4/linode/instances/123/ips/97.107.143.141
- lang: CLI
source: >
linode-cli linodes ip-update 123 \
97.107.143.141 \
--rdns test.example.org
delete:
x-linode-grant: read_write
tags:
- Linode Instances
summary: IPv4 Address Delete
description: >
Deletes a public or private IPv4 address associated with this Linode. This will fail if it is the Linode's last remaining public IPv4 address.
operationId: removeLinodeIP
x-linode-cli-action: ip-delete
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: IP address successfully removed.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/linode/instances/123/ips/97.107.143.141
- lang: CLI
source: >
linode-cli linodes ip-delete 97.107.143.141
/linode/kernels:
x-linode-cli-command: kernels
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Linode Instances
summary: Kernels List
description: |
Lists available Kernels.
operationId: getKernels
x-linode-cli-action: list
responses:
'200':
description: Returns an array of Kernels.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Kernel'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/kernels
- lang: CLI
source: >
linode-cli kernels list
/linode/kernels/{kernelId}:
parameters:
- name: kernelId
in: path
description: ID of the Kernel to look up.
required: true
schema:
type: string
x-linode-cli-command: kernels
get:
tags:
- Linode Instances
summary: Kernel View
description: >
Returns information about a single Kernel.
operationId: getKernel
x-linode-cli-action: view
responses:
'200':
description: A single Kernel object.
content:
application/json:
schema:
$ref: '#/components/schemas/Kernel'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/kernels/linode/latest-64bit
- lang: CLI
source: >
linode-cli kernels view latest-64bit
/linode/instances/{linodeId}/migrate:
parameters:
- name: linodeId
in: path
description: ID of the Linode to migrate.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: DC Migration/Pending Host Migration Initiate
description: >
Initiate a pending host migration that has been scheduled by Linode or
initiate a cross data center (DC) migration. A list of pending migrations,
if any, can be accessed from [GET /account/notifications](/docs/api/account/#notifications-list).
When the migration begins, your Linode will be shutdown if not already off.
If the migration initiated the shutdown, it will reboot the Linode when completed.
To initiate a cross DC migration, you must pass a `region` parameter to the
request body specifying the target data center region.
You can view a list of all available regions and their feature capabilities
from [GET /regions](/docs/api/regions/#regions-list). If your Linode has a DC migration already queued
or you have initiated a previously scheduled migration, you will not be able to initiate
a DC migration until it has completed.
**Note:** Next Generation Network (NGN) data centers do not support IPv6 `/116` pools or IP Failover.
If you have these features enabled on your Linode and attempt to migrate to an NGN data center,
the migration will not initiate. If a Linode cannot be migrated because of an incompatibility,
you will be prompted to select a different data center or contact support.
tags:
- Linode Instances
operationId: migrateLinodeInstance
x-linode-cli-action: migrate
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
content:
'application/json':
schema:
properties:
region:
type: string
description: >
The region to which the Linode will be migrated.
Must be a valid region slug. A list of regions can be viewed
by using the [GET /regions](/docs/api/regions/#regions-list) endpoint.
A cross data center migration will cancel a pending migration
that has not yet been initiated.
A cross data center migration will initiate a `linode_migrate_datacenter_create` event.
example: us-east
upgrade:
type: boolean
description: >
When initiating a cross DC migration, setting this value to
true will also ensure that the Linode is upgraded to the latest
generation of hardware that corresponds to your Linode's Type, if
any free upgrades are available for it.
If no free upgrades are available, and this value is set to true,
then the endpoint will return a 400 error code and the migration
will not be performed.
If the data center set in the `region` field does not allow upgrades,
then the endpoint will return a 400 error code and the migration
will not be performed.
example: false
default: false
responses:
'200':
description: Scheduled migration started
content:
'application/json':
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-central"
}' \
https://api.linode.com/v4/linode/instances/123/migrate
- lang: CLI
source: >
linode-cli linodes migrate 123 --region us-central
/linode/instances/{linodeId}/mutate:
parameters:
- name: linodeId
in: path
description: ID of the Linode to mutate.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Upgrade
description: >
Linodes created with now-deprecated Types are entitled to a free
upgrade to the next generation. A mutating Linode will be allocated any new
resources the upgraded Type provides, and will be subsequently restarted
if it was currently running.
If any actions are currently running or queued, those actions must be
completed first before you can initiate a mutate.
tags:
- Linode Instances
operationId: mutateLinodeInstance
x-linode-cli-action: upgrade
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Whether to automatically resize disks or not.
required: false
content:
application/json:
schema:
type: object
properties:
allow_auto_disk_resize:
type: boolean
description: >
Automatically resize disks when resizing a Linode.
When resizing down to a smaller plan your Linode's
data must fit within the smaller disk size.
example: true
default: true
responses:
'200':
description: Mutate started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/mutate
- lang: CLI
source: >
linode-cli linodes upgrade 123
/linode/instances/{linodeId}/nodebalancers:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Linode NodeBalancers View
description: |
Returns a list of NodeBalancers that are assigned to this Linode and readable by the requesting User.
Read permission to a NodeBalancer can be given to a User by accessing the User's Grants Update
([PUT /account/users/{username}/grants](/docs/api/account/#users-grants-update)) endpoint.
operationId: getLinodeNodeBalancers
x-linode-cli-action: nodebalancers
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: Returns a paginated list of NodeBalancers.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NodeBalancer'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/nodebalancers
- lang: CLI
source: >
linode-cli linodes nodebalancers 123
/linode/instances/{linodeId}/password:
parameters:
- name: linodeId
in: path
description: ID of the Linode for which to reset its root password.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Root Password Reset
description: >
Resets the root password for this Linode.
* Your Linode must be [shut down](/docs/api/linode-instances/#linode-shut-down) for a password reset to complete.
* If your Linode has more than one disk (not counting its swap disk), use the
[Reset Disk Root Password](/docs/api/linode-instances/#disk-root-password-reset) endpoint to update a specific disk's root password.
* A `password_reset` event is generated when a root password reset is successful.
tags:
- Linode Instances
operationId: resetLinodePassword
x-linode-cli-action: linode-reset-password
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: This Linode's new root password.
content:
'application/json':
schema:
required:
- root_pass
properties:
root_pass:
type: string
description: >
The root user's password on this Linode. Linode passwords
must meet a password strength score requirement that is calculated internally
by the API. If the strength requirement is not met, you will receive a
Password does not meet strength requirement error.
example: a$eCure4assw0rd!43v51
responses:
'200':
description: Password Reset.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"root_pass": "a$eCure4assw0rd!43v51"
}' \
https://api.linode.com/v4/linode/instances/123/password
- lang: CLI
source: >
linode-cli linodes linode-reset-password 123 a$eCure4assw0rd!43v51
/linode/instances/{linodeId}/reboot:
parameters:
- name: linodeId
in: path
description: ID of the linode to reboot.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Reboot
description: >
Reboots a Linode you have permission to modify. If any actions are currently running or
queued, those actions must be completed first before you can initiate a reboot.
tags:
- Linode Instances
operationId: rebootLinodeInstance
x-linode-cli-action: reboot
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Optional reboot parameters.
content:
'application/json':
schema:
properties:
config_id:
type: integer
description: >
The Linode Config ID to reboot into. If null or omitted,
the last booted config will be used. If there was no last
booted config and this Linode only has one config, it will
be used. If a config cannot be determined, an error will
be returned.
example: null
responses:
'200':
description: Reboot started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/reboot
- lang: CLI
source: >
linode-cli linodes reboot 123
/linode/instances/{linodeId}/rebuild:
parameters:
- name: linodeId
in: path
description: ID of the Linode to rebuild.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Rebuild
description: >
Rebuilds a Linode you have the `read_write` permission to modify.
A rebuild will first shut down the Linode, delete all disks and configs
on the Linode, and then deploy a new `image` to the Linode with the given
attributes. Additionally:
* Requires an `image` be supplied.
* Requires a `root_pass` be supplied to use for the root User's Account.
* It is recommended to supply SSH keys for the root User using the
`authorized_keys` field.
tags:
- Linode Instances
operationId: rebuildLinodeInstance
x-linode-cli-action: rebuild
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: The requested state your Linode will be rebuilt into.
required: true
content:
application/json:
schema:
type: object
required:
- image
- root_pass
allOf:
- $ref: '#/components/schemas/LinodeRequest'
responses:
'200':
description: Rebuild started.
content:
application/json:
schema:
$ref: '#/components/schemas/Linode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"image": "linode/debian9",
"root_pass": "aComplexP@ssword",
"authorized_keys": [
"ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
],
"authorized_users": [
"myUsername",
"secondaryUsername"
],
"booted": true,
"stackscript_id": 10079,
"stackscript_data": {
"gh_username": "linode"
}
}' \
https://api.linode.com/v4/linode/instances/123/rebuild
- lang: CLI
source: >
linode-cli linodes rebuild 123 \
--image "linode/debian9" \
--root_pass aComplex@Password \
--authorized_keys "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer" \
--authorized_users "myUsername" \
--authorized_users "secondaryUsername" \
--booted true \
--stackscript_id 10079 \
--stackscript_data '{"gh_username": "linode"}'
/linode/instances/{linodeId}/rescue:
parameters:
- name: linodeId
in: path
description: ID of the Linode to rescue.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Boot into Rescue Mode
description: >
Rescue Mode is a safe environment for performing many system recovery
and disk management tasks. Rescue Mode is based on the Finnix recovery
distribution, a self-contained and bootable Linux distribution. You can
also use Rescue Mode for tasks other than disaster recovery, such as
formatting disks to use different filesystems, copying data between
disks, and downloading files from a disk via SSH and SFTP.
* Note that "sdh" is reserved and unavailable during rescue.
tags:
- Linode Instances
operationId: rescueLinodeInstance
x-linode-cli-action: rescue
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: Optional object of devices to be mounted.
required: false
content:
application/json:
schema:
type: object
properties:
devices:
$ref: '#/components/schemas/RescueDevices'
responses:
'200':
description: Rescue started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"devices": {
"sda": {
"disk_id": 124458,
"volume_id": null
},
"sdb": {
"disk_id": null,
"volume_id": null
}
}
}' \
https://api.linode.com/v4/linode/instances/123/rescue
- lang: CLI
source: >
linode-cli linodes rescue 123 \
--devices.sda.disk_id 124458
/linode/instances/{linodeId}/resize:
parameters:
- name: linodeId
in: path
description: ID of the Linode to resize.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Resize
description: >
Resizes a Linode you have the `read_write` permission to a different
Type. If any actions are currently running or queued, those actions must
be completed first before you can initiate a resize. Additionally, the
following criteria must be met in order to resize a Linode:
* The Linode must not have a pending migration.
* Your Account cannot have an outstanding balance.
* The Linode must not have more disk allocation than the new Type allows.
* In that situation, you must first delete or resize the disk to be smaller.
tags:
- Linode Instances
operationId: resizeLinodeInstance
x-linode-cli-action: resize
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
requestBody:
description: >
The Type your current Linode will resize to, and whether to attempt
to automatically resize the Linode's disks.
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: The ID representing the Linode Type.
example: g6-standard-2
x-linode-cli-display: 1
allow_auto_disk_resize:
type: boolean
description: >
Automatically resize disks when resizing a Linode.
When resizing down to a smaller plan your Linode's
data must fit within the smaller disk size.
example: true
default: true
responses:
'200':
description: Resize started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "g6-standard-2"
}' \
https://api.linode.com/v4/linode/instances/123/resize
- lang: CLI
source: >
linode-cli linodes resize 123 \
--type g6-standard-2
/linode/instances/{linodeId}/shutdown:
parameters:
- name: linodeId
in: path
description: ID of the Linode to shutdown.
required: true
schema:
type: integer
x-linode-cli-command: linodes
post:
x-linode-grant: read_write
summary: Linode Shut Down
description: >
Shuts down a Linode you have permission to modify. If any actions are currently running or
queued, those actions must be completed first before you can initiate a shutdown.
tags:
- Linode Instances
operationId: shutdownLinodeInstance
x-linode-cli-action: shutdown
security:
- personalAccessToken: []
- oauth:
- linodes:read_write
responses:
'200':
description: Shutdown started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/linode/instances/123/shutdown
- lang: CLI
source: >
linode-cli linodes shutdown 123
/linode/instances/{linodeId}/transfer:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Network Transfer View
description: >
Returns a Linode's network transfer pool statistics for the current month.
operationId: getLinodeTransfer
x-linode-cli-action: transfer-view
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: A collection of the specified Linode's network transfer statistics.
content:
application/json:
schema:
properties:
used:
type: integer
description: >
The amount of network transfer used by this Linode, in bytes, for the current month's billing cycle.
example: 22956600198
readOnly: true
quota:
type: integer
description: >
The amount of network transfer this Linode adds to your transfer pool, in GB, for the current month's billing cycle.
example: 2000
readOnly: true
billable:
type: integer
description: >
The amount of network transfer this Linode has used, in GB, past your monthly quota.
example: 0
readOnly: true
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/transfer
- lang: CLI
source: >
linode-cli linodes transfer-view 123
/linode/instances/{linodeId}/transfer/{year}/{month}:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: year
in: path
description: Numeric value representing the year to look up.
required: true
schema:
type: integer
minimum: 2000
maximum: 2037
- name: month
in: path
description: Numeric value representing the month to look up.
required: true
schema:
type: integer
minimum: 1
maximum: 12
x-linode-cli-command: linodes
get:
x-linode-grant: read_only
tags:
- Linode Instances
summary: Network Transfer View (year/month)
description: >
Returns a Linode's network transfer statistics for a specific month. The year/month
values must be either a date in the past, or the current month.
operationId: getLinodeTransferByYearMonth
x-linode-cli-skip: true
x-linode-cli-action: transfer-month
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: >
A collection of the specified Linode's network transfer statistics for the requested
month.
content:
application/json:
schema:
properties:
bytes_in:
type: integer
description: >
The amount of inbound public network traffic received by this Linode, in
bytes, for a specific year/month.
example: 30471077120
readOnly: true
bytes_out:
type: integer
description: >
The amount of outbound public network traffic sent by this Linode, in bytes,
for a specific year/month.
example: 22956600198
readOnly: true
bytes_total:
type: integer
description: >
The total amount of public network traffic sent and received by this Linode,
in bytes, for a specific year/month.
example: 53427677318
readOnly: true
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/transfer/2018/01
/linode/instances/{linodeId}/stats:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
tags:
- Linode Instances
summary: Linode Statistics View
description: >
Returns CPU, IO, IPv4, and IPv6 statistics for your Linode
for the past 24 hours.
operationId: getLinodeStats
x-linode-cli-skip: true
x-linode-cli-action: stats
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: The Linode's stats for the past 24 hours.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeStats'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/stats
/linode/instances/{linodeId}/stats/{year}/{month}:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
- name: year
in: path
description: Numeric value representing the year to look up.
required: true
schema:
type: integer
- name: month
in: path
description: Numeric value representing the month to look up.
required: true
schema:
type: integer
minimum: 1
maximum: 12
x-linode-cli-command: linodes
get:
tags:
- Linode Instances
summary: Statistics View (year/month)
description: >
Returns statistics for a specific month. The year/month
values must be either a date in the past, or the current month. If the
current month, statistics will be retrieved for the past 30 days.
operationId: getLinodeStatsByYearMonth
x-linode-cli-skip: true
x-linode-cli-action: stats-month
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: The Linode's statistics for the requested period.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeStats'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/stats/2018/01
/linode/instances/{linodeId}/volumes:
parameters:
- name: linodeId
in: path
description: ID of the Linode to look up.
required: true
schema:
type: integer
x-linode-cli-command: linodes
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Linode Instances
summary: Linode's Volumes List
description: >
View Block Storage Volumes attached to this Linode.
operationId: getLinodeVolumes
x-linode-cli-action: volumes
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: >
Returns an array of Block Storage Volumes attached to this Linode.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Volume'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/linode/instances/123/volumes
- lang: CLI
source: >
linode-cli linode volumes 123
/linode/stackscripts:
x-linode-cli-command: stackscripts
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- StackScripts
summary: StackScripts List
description: >
If the request is not authenticated, only public StackScripts are returned.
For more information on StackScripts, please read our [StackScripts guides](/docs/platform/stackscripts/).
operationId: getStackScripts
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- stackscripts:read_only
responses:
'200':
description: >
A list of StackScripts available to the User, including private
StackScripts owned by the User if the request is authenticated.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/StackScript'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/stackscripts
- lang: CLI
source: >
linode-cli stackscripts list
post:
x-linode-grant: add_stackscripts
tags:
- StackScripts
summary: StackScript Create
description: >
Creates a StackScript in your Account.
operationId: addStackScript
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- stackscripts:read_write
requestBody:
description: The properties to set for the new StackScript.
required: true
content:
application/json:
schema:
required:
- script
- label
- images
allOf:
- $ref: '#/components/schemas/StackScript'
responses:
'200':
description: StackScript successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/StackScript'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "a-stackscript",
"description": "This StackScript installs and configures MySQL",
"images": [
"linode/debian9",
"linode/debian8"
],
"is_public": true,
"rev_note": "Set up MySQL",
"script": "#!/bin/bash"
}' \
https://api.linode.com/v4/linode/stackscripts
- lang: CLI
source: >
linode-cli stackscripts create \
--label a-stackscript \
--description "This StackScript install and configures MySQL" \
--images "linode/debian9" \
--images "linode/debian8" \
--is_public true \
--rev_note "Set up MySQL" \
--script '#!/bin/bash'
/linode/stackscripts/{stackscriptId}:
parameters:
- name: stackscriptId
in: path
description: The ID of the StackScript to look up.
required: true
schema:
type: string
x-linode-cli-command: stackscripts
get:
x-linode-grant: read_only
tags:
- StackScripts
summary: StackScript View
description: >
Returns all of the information about a specified
StackScript, including the contents of the script.
operationId: getStackScript
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- stackscripts:read_only
responses:
'200':
description: A single StackScript.
content:
application/json:
schema:
$ref: '#/components/schemas/StackScript'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/stackscripts/10079
- lang: CLI
source: >
linode-cli stackscripts view 10079
put:
x-linode-grant: read_write
tags:
- StackScripts
summary: StackScript Update
description: >
Updates a StackScript.
**Once a StackScript is made public, it cannot be made private.**
operationId: updateStackScript
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- stackscripts:read_write
requestBody:
description: The fields to update.
content:
application/json:
schema:
$ref: '#/components/schemas/StackScript'
responses:
'200':
description: StackScript was successfully modified.
content:
application/json:
schema:
$ref: '#/components/schemas/StackScript'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "a-stackscript",
"description": "This StackScript installs and configures MySQL",
"images": [
"linode/debian9",
"linode/debian8"
],
"is_public": true,
"rev_note": "Set up MySQL",
"script": "#!/bin/bash"
}' \
https://api.linode.com/v4/linode/stackscripts/10079
- lang: CLI
source: >
linode-cli stackscripts update 10079 \
--label a-stackscript \
--description "This StackScript installs \
and configures MySQL" \
--images "linode/debian9" \
--images "linode/debian8" \
--is_public true \
--rev_note "Set up MySQL" \
--script '#!/bin/bash'
delete:
x-linode-grant: read_write
tags:
- StackScripts
summary: StackScript Delete
description: >
Deletes a private StackScript you have permission to `read_write`. You cannot delete a public StackScript.
operationId: deleteStackScript
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- stackscripts:read_write
responses:
'200':
description: StackScript was deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/linode/stackscripts/10079
- lang: CLI
source: >
linode-cli stackscripts delete 10079
/linode/types:
x-linode-cli-command: linodes
get:
tags:
- Linode Types
summary: Types List
description: >
Returns collection of Linode Types, including pricing and
specifications for each Type. These are used when
[creating](/docs/api/linode-instances/#linode-create)
or [resizing](/docs/api/linode-instances/#linode-resize)
Linodes.
x-linode-redoc-load-ids: true
operationId: getLinodeTypes
x-linode-cli-action: types
responses:
'200':
description: A collection of Linode Types.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LinodeType'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/types
- lang: CLI
source: >
linode-cli linodes types
/linode/types/{typeId}:
parameters:
- name: typeId
in: path
description: The ID of the Linode Type to look up.
required: true
schema:
type: string
x-linode-cli-command: linodes
get:
tags:
- Linode Types
summary: Type View
description: >
Returns information about a specific Linode Type, including pricing and
specifications. This is used when
[creating](/docs/api/linode-instances/#linode-create)
or [resizing](/docs/api/linode-instances/#linode-resize)
Linodes.
operationId: getLinodeType
x-linode-cli-action: type-view
responses:
'200':
description: A single Linode Type.
content:
application/json:
schema:
$ref: '#/components/schemas/LinodeType'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/linode/types/g6-standard-2
- lang: CLI
source: >
linode-cli linodes type-view g6-standard-2
/lke/clusters:
x-linode-cli-command: lke
get:
operationId: getLKEClusters
x-linode-cli-action: clusters-list
x-linode-grant: read_only
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Clusters List
description: >
Lists current Kubernetes clusters available on your account.
responses:
'200':
description: Returns an array of all Kubernetes clusters on your Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LKECluster'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters
- lang: CLI
source: >
linode-cli lke clusters-list
post:
operationId: createLKECluster
x-linode-cli-action: cluster-create
x-linode-charge: true
x-linode-grant: add_clusters
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Cluster Create
description: |
Creates a Kubernetes cluster. The Kubernetes cluster will be created
asynchronously. You can use the events system to determine when the
Kubernetes cluster is ready to use. Please note that it often takes 2-5 minutes before the
[Kubernetes API server endpoint](/docs/api/linode-kubernetes-engine-lke/#kubernetes-api-endpoints-list) and
the [Kubeconfig file](/docs/api/linode-kubernetes-engine-lke/#kubeconfig-view) for the new cluster
are ready.
requestBody:
description: Configuration for the Kubernetes cluster
x-linode-cli-allowed-defaults:
- region
content:
application/json:
schema:
type: object
required:
- label
- region
- k8s_version
- node_pools
properties:
label:
$ref: '#/components/schemas/LKECluster/properties/label'
region:
$ref: '#/components/schemas/LKECluster/properties/region'
k8s_version:
$ref: '#/components/schemas/LKECluster/properties/k8s_version'
tags:
$ref: '#/components/schemas/LKECluster/properties/tags'
node_pools:
type: array
required:
- type
- count
items:
$ref: '#/components/schemas/LKENodePoolRequestBody'
control_plane:
type: object
description: >
Defines settings for the Kubernetes Control Plane. Allows for the enabling of High Availability (HA) for Control Plane Components. Enabling High Availability for LKE is an **irreversible** change.
properties:
high_availability:
type: boolean
description: >
Defines whether High Availability is enabled for the Control Plane Components of the cluster. Defaults to `false`.
example: true
responses:
'200':
description: Kubernetes cluster creation has started.
content:
application/json:
schema:
$ref: '#/components/schemas/LKECluster'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "cluster12345",
"region": "us-central",
"k8s_version": "1.23",
"tags": ["ecomm", "blogs"],
"control_plane": {
"high_availability": true
},
"node_pools": [
{
"type": "g6-standard-4",
"count": 6,
"autoscaler": {
"enabled": true,
"max": 12,
"min": 3
}
},
{
"type": "g6-standard-8",
"count": 3
}
]
}' \
https://api.linode.com/v4/lke/clusters
- lang: CLI
source: >
linode-cli lke cluster-create \
--label cluster12345 \
--region us-central \
--k8s_version 1.23 \
--control_plane.high_availability true \
--node_pools.type g6-standard-4 --node_pools.count 6 \
--node_pools.type g6-standard-8 --node_pools.count 3 \
--node_pools.autoscaler.enabled true \
--node_pools.autoscaler.max 12 \
--node_pools.autoscaler.min 3 \
--tags ecomm
/lke/clusters/{clusterId}:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKECluster
x-linode-cli-action: cluster-view
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Cluster View
description: >
Get a specific Cluster by ID.
responses:
'200':
description: Returns a single Kubernetes cluster.
content:
application/json:
schema:
$ref: '#/components/schemas/LKECluster'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345
- lang: CLI
source:
linode-cli lke cluster-view 12345
put:
operationId: putLKECluster
x-linode-cli-action: cluster-update
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Cluster Update
description: >
Updates a Kubernetes cluster.
requestBody:
description: The fields to update the Kubernetes cluster.
content:
application/json:
schema:
properties:
label:
$ref: '#/components/schemas/LKECluster/properties/label'
tags:
type: array
items:
type: string
example:
- prod
- monitoring
- ecomm
- blog
description: >
An array of tags applied to the Kubernetes cluster. Tags are for organizational purposes only.
To delete a tag, exclude it from your `tags` array.
k8s_version:
type: string
description: >
The desired Kubernetes version for this Kubernetes cluster in the format of
<major>.<minor>. New and recycled Nodes in this cluster will be installed with the
latest available patch for the Cluster's Kubernetes version.
When upgrading the Kubernetes version, only the next latest minor version following the current
version can be deployed. For example, a cluster with Kubernetes version 1.19 can be upgraded to
version 1.20, but not directly to 1.21.
The Kubernetes version of a cluster can not be downgraded.
control_plane:
type: object
description: |
Defines settings for the Kubernetes Control Plane. Allows for the enabling of High Availability (HA) for Control Plane Components.
Enabling High Availability for LKE is an **irreversible** change.
When upgrading pre-existing LKE clusters to use the HA Control Plane, the following changes will additionally occur:
- All nodes will be deleted and new nodes will be created to replace them.
- Any local storage (such as `hostPath` volumes) will be erased.
- The upgrade process may take several minutes to complete, as nodes will be replaced on a rolling basis.
properties:
high_availability:
type: boolean
description: >
Defines whether High Availability is enabled for the Control Plane Components of the cluster. Defaults to `false`.
example: true
responses:
'200':
description: Returns a single Kubernetes cluster.
content:
application/json:
schema:
properties:
label:
$ref: '#/components/schemas/LKECluster/properties/label'
tags:
type: array
items:
type: string
example:
- prod
- monitoring
- ecomm
- blog
description: >
An array of tags applied to the Kubernetes cluster. Tags are for organizational purposes only.
To delete a tag, exclude it from your `tags` array.
created:
$ref: '#/components/schemas/LKECluster/properties/created'
updated:
$ref: '#/components/schemas/LKECluster/properties/updated'
region:
$ref: '#/components/schemas/LKECluster/properties/region'
k8s_version:
$ref: '#/components/schemas/LKECluster/properties/k8s_version'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "lkecluster54321"
"tags" : ["ecomm", "blog", "prod", "monitoring"]
"control_plane": {
"high_availability": true
},
"k8s_version": "1.17"
}' \
https://api.linode.com/v4/lke/clusters/12345
- lang: CLI
source: >
linode-cli lke cluster-update 12345 \
--label lkecluster54321 \
--control_plane.high_availability true \
--k8s_version 1.23 \
--tags ecomm \
--tags blog \
--tags prod \
--tags monitoring
delete:
operationId: deleteLKECluster
x-linode-cli-action: cluster-delete
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Cluster Delete
description: |
Deletes a Cluster you have permission to `read_write`.
**Deleting a Cluster is a destructive action and cannot be undone.**
Deleting a Cluster:
- Deletes all Linodes in all pools within this Kubernetes cluster
- Deletes all supporting Kubernetes services for this Kubernetes
cluster (API server, etcd, etc)
- Deletes all NodeBalancers created by this Kubernetes cluster
- Does not delete any of the volumes created by this Kubernetes
cluster
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/lke/clusters/12345
- lang: CLI
source: >
linode-cli lke cluster-delete 12345
/lke/clusters/{clusterId}/pools:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKEClusterPools
x-linode-cli-action: pools-list
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pools List
description: >
Returns all active Node Pools on a Kubernetes cluster.
responses:
'200':
description: Returns an array of all Pools in this Kubernetes cluster.
content:
application/json:
x-linode-cli-nested-list: nodes
x-linode-cli-use-schema:
type: object
properties:
id:
x-linode-cli-display: 1
type:
x-linode-cli-display: 2
nodes.id:
x-linode-cli-display: 3
nodes.instance_id:
x-linode-cli-display: 4
nodes.status:
x-linode-cli-display: 5
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LKENodePool'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/pools
- lang: CLI
source: >
linode-cli lke pools-list 12345
post:
operationId: postLKEClusterPools
x-linode-cli-action: pool-create
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pool Create
description: >
Creates a new Node Pool for the designated Kubernetes cluster.
requestBody:
description: Configuration for the Node Pool
required: true
content:
application/json:
schema:
type: object
required:
- type
- count
allOf:
- $ref: '#/components/schemas/LKENodePoolRequestBody'
responses:
'200':
description: Node Pool has been created.
content:
application/json:
schema:
$ref: '#/components/schemas/LKENodePool'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "g6-standard-4",
"count": 6,
"tags": ["example-tag"],
"autoscaler": {
"enabled": true,
"max": 12,
"min": 3
}
}' \
https://api.linode.com/v4/lke/clusters/12345/pools
- lang: CLI
source: >
linode-cli lke pool-create 12345 \
--type g6-standard-4 \
--count 6 \
--tags example-tag \
--autoscaler.enabled true \
--autoscaler.max 12 \
--autoscaler.min 3
/lke/clusters/{clusterId}/recycle:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster which contains nodes to be recycled.
required: true
schema:
type: integer
x-linode-cli-command: lke
post:
operationId: postLKEClusterRecycle
x-linode-cli-action: cluster-nodes-recycle
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Cluster Nodes Recycle
description: |
Recycles all nodes in all pools of a designated Kubernetes Cluster. All Linodes within the Cluster will be deleted
and replaced with new Linodes on a rolling basis, which may take several minutes. Replacement Nodes are
installed with the latest available [patch version](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/release/versioning.md#kubernetes-release-versioning) for the Cluster's current Kubernetes minor release.
**Any local storage on deleted Linodes (such as "hostPath" and "emptyDir" volumes, or "local" PersistentVolumes) will be erased.**
responses:
'200':
description: Recycle request succeeded and is in progress.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/lke/clusters/12345/recycle
- lang: CLI
source: >
linode-cli lke cluster-nodes-recycle 12345
/lke/clusters/{clusterId}/pools/{poolId}:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
- name: poolId
in: path
description: ID of the Pool to look up
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKENodePool
x-linode-cli-action: pool-view
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pool View
description: >
Get a specific Node Pool by ID.
responses:
'200':
description: Returns the requested Node Pool.
content:
application/json:
schema:
$ref: '#/components/schemas/LKENodePool'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/pools/456
- lang: CLI
source: >
linode-cli lke pool-view 12345 456
put:
operationId: putLKENodePool
x-linode-cli-action: pool-update
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pool Update
description: |
Updates a Node Pool's count and autoscaler configuration.
Linodes will be created or deleted to match changes to the Node Pool's count.
**Any local storage on deleted Linodes (such as "hostPath" and "emptyDir" volumes, or "local" PersistentVolumes) will be erased.**
requestBody:
description: The fields to update
content:
application/json:
schema:
properties:
count:
$ref: '#/components/schemas/LKENodePoolRequestBody/properties/count'
autoscaler:
$ref: '#/components/schemas/LKENodePoolRequestBody/properties/autoscaler'
responses:
'200':
description: Node Pool was successfully modified.
content:
application/json:
schema:
$ref: '#/components/schemas/LKENodePool'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"count": 6,
"autoscaler": {
"enabled": true,
"max": 12,
"min": 3
}' \
https://api.linode.com/v4/lke/clusters/12345/pools/456
- lang: CLI
source: >
linode-cli lke pool-update 12345 456 \
--count 6 \
--autoscaler.enabled true \
--autoscaler.max 12 \
--autoscaler.min 3
delete:
operationId: deleteLKENodePool
x-linode-cli-action: pool-delete
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pool Delete
description: |
Delete a specific Node Pool from a Kubernetes cluster.
**Deleting a Node Pool is a destructive action and cannot be undone.**
Deleting a Node Pool will delete all Linodes within that Pool.
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/lke/clusters/12345/pools/456
- lang: CLI
source: >
linode-cli lke pool-delete 12345 456
/lke/clusters/{clusterId}/pools/{poolId}/recycle:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster this Node Pool is attached to.
required: true
schema:
type: integer
- name: poolId
in: path
description: ID of the Node Pool to be recycled.
required: true
schema:
type: integer
x-linode-cli-command: lke
post:
operationId: postLKEClusterPoolRecycle
x-linode-cli-action: pool-recycle
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Pool Recycle
description: |
Recycles a Node Pool for the designated Kubernetes Cluster. All Linodes within the Node Pool will be deleted
and replaced with new Linodes on a rolling basis, which may take several minutes. Replacement Nodes are
installed with the latest available patch for the Cluster's Kubernetes Version.
**Any local storage on deleted Linodes (such as "hostPath" and "emptyDir" volumes, or "local" PersistentVolumes) will be erased.**
responses:
'200':
description: Recycle request succeeded and is in progress.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/lke/clusters/12345/pools/456/recycle
- lang: CLI
source: >
linode-cli lke pool-recycle 12345 456
/lke/clusters/{clusterId}/nodes/{nodeId}:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster containing the Node.
required: true
schema:
type: integer
- name: nodeId
in: path
description: ID of the Node to look up.
required: true
schema:
type: string
x-linode-cli-command: lke
get:
operationId: getLKEClusterNode
x-linode-cli-action: node-view
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node View
description: >
Returns the values for a specified node object.
responses:
'200':
description: Returns the values of a node object in the form that it appears currently in the node pool array.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: >
The selected node in the cluster.
properties:
id:
type: string
readOnly: true
description: >
The Node's ID.
example: "12345-6aa78910bc"
instance_id:
type: integer
description: >
The Linode's ID. If no Linode is currently provisioned for this Node, this is `null`.
example: 123456
status:
type: string
description: >
The creation status of this Node. This status is distinct from this Node's readiness as a
Kubernetes Node Object as determined by the command `kubectl get nodes`.
`not_ready` indicates that the Linode is still being created.
`ready` indicates that the Linode has successfully been created and is running Kubernetes software.
enum:
- ready
- not_ready
example: ready
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/nodes/12345-6aa78910bc
- lang: CLI
source: >
linode-cli lke node-view 123456 12345-6aa78910bc
delete:
operationId: deleteLKEClusterNode
x-linode-cli-action: node-delete
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Delete
description: |
Deletes a specific Node from a Node Pool.
**Deleting a Node is a destructive action and cannot be undone.**
Deleting a Node will reduce the size of the Node Pool it belongs to.
responses:
'200':
description: Delete successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/lke/clusters/12345/nodes/12345-6aa78910bc
- lang: CLI
source: >
linode-cli lke node-delete 12345 12345-6aa78910bc
/lke/clusters/{clusterId}/nodes/{nodeId}/recycle:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster containing the Node.
required: true
schema:
type: integer
- name: nodeId
in: path
description: ID of the Node to be recycled.
required: true
schema:
type: string
x-linode-cli-command: lke
post:
operationId: postLKEClusterNodeRecycle
x-linode-cli-action: node-recycle
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Node Recycle
description: |
Recycles an individual Node in the designated Kubernetes Cluster. The Node will be deleted
and replaced with a new Linode, which may take a few minutes. Replacement Nodes are
installed with the latest available patch for the Cluster's Kubernetes Version.
**Any local storage on deleted Linodes (such as "hostPath" and "emptyDir" volumes, or "local" PersistentVolumes) will be erased.**
responses:
'200':
description: Recycle request succeeded and is in progress.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/lke/clusters/12345/nodes/12345-6aa78910bc/recycle
- lang: CLI
source: >
linode-cli lke node-recycle 12345 12345-6aa78910bc
/lke/clusters/{clusterId}/api-endpoints:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKEClusterAPIEndpoints
x-linode-cli-action: api-endpoints-list
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes API Endpoints List
description: >
List the Kubernetes API server endpoints for this cluster. Please note that it often takes
2-5 minutes before the endpoint is ready after first [creating a new cluster](/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-create).
responses:
'200':
description: Returns the Kubernetes API server endpoints for this cluster.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
description: >
The Kubernetes API server endpoints for this cluster.
properties:
endpoint:
type: string
readOnly: true
description: >
A Kubernetes API server endpoint for this cluster.
example: "https://192.0.2.1:6443"
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/api-endpoints
- lang: CLI
source: >
linode-cli lke api-endpoints-list 12345
/lke/clusters/{clusterId}/dashboard:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKEClusterDashboard
x-linode-cli-action: cluster-dashboard-url
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Cluster Dashboard URL View
description: |
Get a [Kubernetes Dashboard](https://github.com/kubernetes/dashboard) access URL for this Cluster, which enables performance of administrative tasks through a web interface.
Dashboards are installed for Clusters by default.
To access the Cluster Dashboard login prompt, enter the URL in a web browser. Select either **Token** or **Kubeconfig** authentication, then select **Sign in**.
For additional guidance on using the Cluster Dashboard, see the [Navigating the Cluster Dashboard](/docs/guides/using-the-kubernetes-dashboard-on-lke/#navigating-the-cluster-dashboard) section of our guide on [Using the Kubernetes Dashboard on LKE](/docs/guides/using-the-kubernetes-dashboard-on-lke/).
responses:
'200':
description: Returns a Kubernetes Cluster Dashboard URL.
content:
application/json:
schema:
type: object
properties:
url:
type: string
example: https://example.dashboard.linodelke.net
description: The Cluster Dashboard access URL.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/dashboard
- lang: CLI
source:
linode-cli lke cluster-dashboard-url 12345
/lke/clusters/{clusterId}/kubeconfig:
parameters:
- name: clusterId
in: path
description: ID of the Kubernetes cluster to look up.
required: true
schema:
type: integer
x-linode-cli-command: lke
get:
operationId: getLKEClusterKubeconfig
x-linode-cli-action: kubeconfig-view
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubeconfig View
description: |
Get the Kubeconfig file for a Cluster. Please note that it often takes 2-5 minutes before
the Kubeconfig file is ready after first [creating a new cluster](/docs/api/linode-kubernetes-engine-lke/#kubernetes-cluster-create).
responses:
'200':
description: Returns the Base64-encoded Kubeconfig file for this Kubernetes cluster.
content:
application/json:
schema:
type: object
properties:
kubeconfig:
type: string
readOnly: true
description: >
The Base64-encoded Kubeconfig file for this Cluster.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/clusters/12345/kubeconfig
- lang: CLI
source: >
linode-cli lke kubeconfig-view 12345
delete:
operationId: deleteLKEClusterKubeconfig
x-linode-cli-action: kubeconfig-delete
security:
- personalAccessToken: []
- oauth:
- lke:read_write
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubeconfig Delete
description: |
Delete and regenerate the Kubeconfig file for a Cluster.
responses:
'200':
description: Kubeconfig file deleted and regenerated successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/lke/clusters/12345/kubeconfig
- lang: CLI
source: >
linode-cli lke kubeconfig-delete 12345
/lke/versions:
x-linode-cli-command: lke
get:
operationId: getLKEVersions
x-linode-cli-action: versions-list
x-linode-grant: read_only
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Versions List
description: >
List the Kubernetes versions available for deployment
to a Kubernetes cluster.
responses:
'200':
description: >
Returns a list of Kubernetes versions available for deployment
to a Kubernetes cluster.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LKEVersion'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/versions
- lang: CLI
source: >
linode-cli lke versions-list
/lke/versions/{version}:
parameters:
- name: version
in: path
required: true
description: The LKE version to view.
schema:
type: string
x-linode-cli-command: lke
get:
operationId: getLKEVersion
x-linode-cli-action: version-view
x-linode-grant: read_only
security:
- personalAccessToken: []
- oauth:
- lke:read_only
tags:
- Linode Kubernetes Engine (LKE)
summary: Kubernetes Version View
description: >
View a Kubernetes version available for deployment
to a Kubernetes cluster.
responses:
'200':
description: >
Returns a Kubernetes version object that is available for deployment
to a Kubernetes cluster.
content:
application/json:
schema:
$ref: '#/components/schemas/LKEVersion'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/lke/versions/1.23
- lang: CLI
source: >
linode-cli lke version-view 1.23
/longview/clients:
x-linode-cli-command: longview
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Longview
summary: Longview Clients List
description: >
Returns a paginated list of Longview Clients you have access
to. Longview Client is used to monitor stats on your Linode
with the help of the Longview Client application.
operationId: getLongviewClients
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- longview:read_only
responses:
'200':
description: A paginated list of Longview Clients.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LongviewClient'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/longview/clients
- lang: CLI
source: >
linode-cli longview list
post:
x-linode-grant: add_longview
tags:
- Longview
summary: Longview Client Create
description: >
Creates a Longview Client. This Client will not begin monitoring
the status of your server until you configure the Longview
Client application on your Linode using the returning `install_code`
and `api_key`.
operationId: createLongviewClient
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- longview:read_write
requestBody:
description: Information about the LongviewClient to create.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewClient'
responses:
'200':
description: Longview Client created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "client789"
}' \
https://api.linode.com/v4/longview/clients
- lang: CLI
source: >
linode-cli longview create \
--label client789
/longview/clients/{clientId}:
parameters:
- name: clientId
in: path
required: true
description: The Longview Client ID to access.
schema:
type: integer
x-linode-cli-command: longview
get:
x-linode-grant: read_only
tags:
- Longview
summary: Longview Client View
description: >
Returns a single Longview Client you can access.
operationId: getLongviewClient
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- longview:read_only
responses:
'200':
description: The requested Longview Client.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/longview/clients/789
- lang: CLI
source: >
linode-cli longview view 789
put:
x-linode-grant: read_write
tags:
- Longview
summary: Longview Client Update
description: >
Updates a Longview Client. This cannot update how it monitors your
server; use the Longview Client application on your Linode for
monitoring configuration.
operationId: updateLongviewClient
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- longview:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewClient'
responses:
'200':
description: Longview Client updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewClient'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "client789"
}' \
https://api.linode.com/v4/longview/clients/789
- lang: CLI
source: >
linode-cli longview update 789 \
--label client789
delete:
x-linode-grant: read_write
tags:
- Longview
summary: Longview Client Delete
description: >
Deletes a Longview Client from your Account.
**All information stored for this client will be lost.**
This _does not_ uninstall the Longview Client application for your
Linode - you must do that manually.
operationId: deleteLongviewClient
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- longview:read_write
responses:
'200':
description: Longview Client deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/longview/clients/789
- lang: CLI
source: >
linode-cli longview delete 789
/longview/plan:
x-linode-cli-command: longview
get:
tags:
- Longview
summary: Longview Plan View
description: >
Get the details of your current Longview plan. This returns a `LongviewSubscription` object
for your current Longview Pro plan, or an empty set `{}` if your current plan is Longview Free.
You must have at least one of the following `global` [User Grants](/docs/api/account/#users-grants-view)
in order to access this endpoint:
- `"account_access": read_write`
- `"account_access": read_only`
- `"longview_subscription": true`
- `"add_longview": true`
To update your subscription plan, send a request to [Update Longview Plan](/docs/api/longview/#longview-plan-update).
operationId: getLongviewPlan
x-linode-cli-action: plan-view
security:
- personalAccessToken: []
- oauth:
- longview:read_only
responses:
'200':
description: The Longview plan details for this account.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewSubscription'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/longview/plan
- lang: CLI
source: >
linode-cli longview plan-view
put:
tags:
- Longview
summary: Longview Plan Update
description: >
Update your Longview plan to that of the given subcription ID. This returns a `LongviewSubscription` object for
the updated Longview Pro plan, or an empty set `{}` if the updated plan is Longview Free.
You must have `"longview_subscription": true` configured as a `global`
[User Grant](/docs/api/account/#users-grants-view) in order to access this endpoint.
You can send a request to the [List Longview Subscriptions](/docs/api/longview/#longview-subscriptions-list)
endpoint to receive the details, including `id`'s, of each plan.
operationId: updateLongviewPlan
x-linode-cli-action: plan-update
security:
- personalAccessToken: []
- oauth:
- longview:read_write
requestBody:
description: Update your Longview subscription plan.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewPlan'
responses:
'200':
description: The updated Longview plan details for this account.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewSubscription'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"longview_subscription": "longview-10"
}' \
https://api.linode.com/v4/longview/plan
- lang: CLI
source: >
linode-cli longview plan-update --longview_subscription longview-10
/longview/subscriptions:
x-linode-cli-command: longview
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Longview
summary: Longview Subscriptions List
description: >
Returns a paginated list of available Longview Subscriptions. This is
a public endpoint and requires no authentication.
operationId: getLongviewSubscriptions
x-linode-cli-action: subscriptions-list
responses:
'200':
description: A paginated list of Longview Subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LongviewSubscription'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/longview/subscriptions
- lang: CLI
source: >
linode-cli longview subscriptions-list
/longview/subscriptions/{subscriptionId}:
parameters:
- name: subscriptionId
in: path
required: true
description: The Longview Subscription to look up.
schema:
type: string
x-linode-cli-command: longview
get:
tags:
- Longview
summary: Longview Subscription View
description: >
Get the Longview plan details as a single `LongviewSubscription` object for the provided subscription ID. This is a public endpoint
and requires no authentication.
operationId: getLongviewSubscription
x-linode-cli-action: subscription-view
responses:
'200':
description: The requested Longview Subscription details.
content:
application/json:
schema:
$ref: '#/components/schemas/LongviewSubscription'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/longview/subscriptions/longview-10
- lang: CLI
source: >
linode-cli longview subscription-view \
longview-10
/managed/contacts:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Managed
summary: Managed Contacts List
description: |
Returns a paginated list of Managed Contacts on your Account.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedContacts
x-linode-cli-action: contacts-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of ManagedContacts
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ManagedContact'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/contacts
- lang: CLI
source: >
linode-cli managed contacts-list
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Contact Create
description: |
Creates a Managed Contact. A Managed Contact is someone Linode
special forces can contact in the course of attempting to resolve an issue
with a Managed Service.
This command can only be accessed by the unrestricted users of an account.
operationId: createManagedContact
x-linode-cli-action: contact-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the contact to create.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedContact'
responses:
'200':
description: Contact created.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedContact'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"name": "John Doe",
"email": "john.doe@example.org",
"phone": {
"primary": "123-456-7890",
"secondary": null
},
"group": "on-call"
}' \
https://api.linode.com/v4/managed/contacts
- lang: CLI
source: >
linode-cli managed contact-create \
--name "John Doe" \
--email "john.doe@example.org" \
--phone.primary "123-456-7890"
/managed/contacts/{contactId}:
parameters:
- name: contactId
in: path
required: true
description: The ID of the contact to access.
schema:
type: integer
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Contact View
description: |
Returns a single Managed Contact.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedContact
x-linode-cli-action: contact-view
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: The requested Managed Contact.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedContact'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/contacts/567
- lang: CLI
source: >
linode-cli managed contact-view 567
put:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Contact Update
description: >
Updates information about a Managed Contact.
This command can only be accessed by the unrestricted users of an account.
operationId: updateManagedContact
x-linode-cli-action: contact-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedContact'
responses:
'200':
description: Contact updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedContact'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"name": "John Doe",
"email": "john.doe@example.org",
"phone": {
"primary": "123-456-7890",
"secondary": null
},
"group": "on-call"
}' \
https://api.linode.com/v4/managed/contacts/567
- lang: CLI
source: >
linode-cli managed contact-update 567 \
--name "John Doe" \
--email "john.doe@example.org" \
--phone.primary "123-456-7890"
delete:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Contact Delete
description: |
Deletes a Managed Contact.
This command can only be accessed by the unrestricted users of an account.
operationId: deleteManagedContact
x-linode-cli-action: contact-delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Contact deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/managed/contacts/567
- lang: CLI
source: >
linode-cli managed contact-delete 567
/managed/credentials:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Managed
summary: Managed Credentials List
description: |
Returns a paginated list of Managed Credentials on your Account.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedCredentials
x-linode-cli-action: credentials-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of ManagedCredentials
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ManagedCredential'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/credentials
- lang: CLI
source: >
linode-cli managed credentials-list
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Credential Create
description: |
Creates a Managed Credential. A Managed Credential is stored securely
to allow Linode special forces to access your Managed Services and resolve
issues.
This command can only be accessed by the unrestricted users of an account.
operationId: createManagedCredential
x-linode-cli-action: credential-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the Credential to create.
content:
application/json:
schema:
required:
- label
- password
allOf:
- $ref: '#/components/schemas/ManagedCredential'
- type: object
properties:
username:
type: string
minLength: 0
maxLength: 5000
description: >
The username to use when accessing the Managed Service.
example: johndoe
password:
type: string
description: >
The password to use when accessing the Managed Service.
example: s3cur3P@ssw0rd
responses:
'200':
description: Credential created.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedCredential'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "prod-password-1",
"username": "johndoe",
"password": "s3cur3P@ssw0rd"
}' \
https://api.linode.com/v4/managed/credentials
- lang: CLI
source: >
linode-cli managed credential-create \
--label prod-password-1 \
--username johndoe \
--password s3cur3P@ssw0rd
/managed/credentials/{credentialId}:
parameters:
- name: credentialId
in: path
required: true
description: The ID of the Credential to access.
schema:
type: integer
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Credential View
description: |
Returns a single Managed Credential.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedCredential
x-linode-cli-action: credential-view
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: The requested Managed Credential.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedCredential'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/credentials/9991
- lang: CLI
source: >
linode-cli managed credential-view 9991
put:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Credential Update
description: >
Updates the label of a Managed Credential. This endpoint
does not update the username and password for a Managed Credential.
To do this, use the Managed Credential Username and Password Update
([POST /managed/credentials/{credentialId}/update](/docs/api/managed/#managed-credential-username-and-password-update))
endpoint instead.
This command can only be accessed by the unrestricted users of an account.
operationId: updateManagedCredential
x-linode-cli-action: credential-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedCredential'
responses:
'200':
description: Credential updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedCredential'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "prod-password-1"
}' \
https://api.linode.com/v4/managed/credentials/9991
- lang: CLI
source: >
linode-cli managed credential-update 9991 \
--label prod-password-1
/managed/credentials/{credentialId}/update:
parameters:
- name: credentialId
in: path
required: true
description: The ID of the Credential to update.
schema:
type: integer
x-linode-cli-command: managed
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Credential Username and Password Update
description: |
Updates the username and password for a Managed Credential.
This command can only be accessed by the unrestricted users of an account.
operationId: updateManagedCredentialUsernamePassword
x-linode-cli-action: credential-update-username-password
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The new username and password to assign to the
Managed Credential.
content:
application/json:
schema:
required:
- password
properties:
username:
type: string
minLength: 0
maxLength: 5000
description: >
The username to use when accessing the Managed Service.
example: johndoe
password:
type: string
description: >
The password to use when accessing the Managed Service.
example: s3cur3P@ssw0rd
responses:
'200':
description: Credential username and password updated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"username": "johndoe",
"password": "s3cur3P@ssw0rd"
}' \
https://api.linode.com/v4/managed/credentials/9991/update
- lang: CLI
source: >
linode-cli managed credential-update-username-password 9991 \
--username johndoe \
--password s3cur3P@ssw0rd
/managed/credentials/{credentialId}/revoke:
parameters:
- name: credentialId
in: path
required: true
description: The ID of the Credential to access.
schema:
type: integer
x-linode-cli-command: managed
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Credential Delete
description: |
Deletes a Managed Credential. Linode special forces will no longer
have access to this Credential when attempting to resolve issues.
This command can only be accessed by the unrestricted users of an account.
operationId: deleteManagedCredential
x-linode-cli-action: credential-revoke
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Credential deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/managed/credentials/9991
- lang: CLI
source: >
linode-cli managed credential-revoke 9991
/managed/credentials/sshkey:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed SSH Key View
description: |
Returns the unique SSH public key assigned to your Linode account's
Managed service. If you [add this public key](/docs/platform/linode-managed/#adding-the-public-key) to a Linode on your account,
Linode special forces will be able to log in to the Linode with this key
when attempting to resolve issues.
This command can only be accessed by the unrestricted users of an account.
operationId: viewManagedSSHKey
x-linode-cli-action: credential-sshkey-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested Managed SSH public key.
content:
application/json:
schema:
type: object
description: >
A unique SSH public key that allows Linode's special forces
to access a Managed server to respond to Issues.
properties:
ssh_key:
type: string
description: >
The unique SSH public key assigned to your Linode account's Managed service.
example: ssh-rsa AAAAB...oD2ZQ== managedservices@linode
readOnly: true
x-linode-cli-display: 1
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/credentials/sshkey
- lang: CLI
source: >
linode-cli managed credential-sshkey-view
/managed/issues:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Managed
summary: Managed Issues List
description: |
Returns a paginated list of recent and ongoing issues detected on your
Managed Services.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedIssues
x-linode-cli-action: issues-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
A paginated list of open or ongoing Managed Issues.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ManagedIssue'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/issues
- lang: CLI
source: >
linode-cli managed issues-list
/managed/issues/{issueId}:
parameters:
- name: issueId
in: path
required: true
description: The Issue to look up.
schema:
type: integer
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Issue View
description: |
Returns a single Issue that is impacting or did impact one of your
Managed Services.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedIssue
x-linode-cli-action: issue-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested issue.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedIssue'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/issues/823
- lang: CLI
source: >
linode-cli managed issue-view 823
/managed/linode-settings:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Managed
summary: Managed Linode Settings List
description: |
Returns a paginated list of Managed Settings for your Linodes. There will
be one entry per Linode on your Account.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedLinodeSettings
x-linode-cli-action: linode-settings-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
A paginated list of Managed settings for your Linodes.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ManagedLinodeSettings'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/linode-settings
- lang: CLI
source: >
linode-cli managed linode-settings-list
/managed/linode-settings/{linodeId}:
parameters:
- name: linodeId
in: path
required: true
description: The Linode ID whose settings we are accessing.
schema:
type: integer
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Linode's Managed Settings View
description: |
Returns a single Linode's Managed settings.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedLinodeSetting
x-linode-cli-action: linode-setting-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested Linode's Managed settings.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedLinodeSettings'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/linode-settings/123
- lang: CLI
source: >
linode-cli managed linode-setting-view 123
put:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Linode's Managed Settings Update
description: >
Updates a single Linode's Managed settings.
This command can only be accessed by the unrestricted users of an account.
operationId: updateManagedLinodeSetting
x-linode-cli-action: linode-setting-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The settings to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedLinodeSettings'
responses:
'200':
description: Settings updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedLinodeSettings'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"ssh": {
"access": true,
"user": "linode",
"ip": "12.34.56.78",
"port": 22
}
}' \
https://api.linode.com/v4/managed/linode-settings/123
- lang: CLI
source: >
linode-cli managed linode-setting-update \
7833234 \
--ssh.access true \
--ssh.user linode \
--ssh.port 22 \
--ssh.ip 12.34.56.78
/managed/services:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Services List
description: |
Returns a paginated list of Managed Services on your Account. These
are the services Linode Managed is monitoring and will report and attempt
to resolve issues with.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedServices
x-linode-cli-action: services-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of Managed Services
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ManagedService'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/services
- lang: CLI
source: >
linode-cli managed services-list
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service Create
description: |
Creates a Managed Service. Linode Managed will begin monitoring this
service and reporting and attempting to resolve any Issues.
This command can only be accessed by the unrestricted users of an account.
operationId: createManagedService
x-linode-cli-action: service-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the service to monitor.
content:
application/json:
schema:
required:
- label
- service_type
- address
- timeout
allOf:
- $ref: '#/components/schemas/ManagedService'
responses:
'200':
description: Service created.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"service_type": "url",
"label": "prod-1",
"address": "https://example.org",
"timeout": 30,
"body": "it worked",
"consultation_group": "on-call",
"notes": "The service name is my-cool-application",
"credentials": [
9991
]
}' \
https://api.linode.com/v4/managed/services
- lang: CLI
source: >
linode-cli managed service-create \
--service_type url \
--label prod-1 \
--address "https://example.org" \
--timeout 30 \
--body "it worked" \
--consultation_group on-call \
--notes "The service name is \
my-cool-application" \
--credentials 9991
/managed/services/{serviceId}:
parameters:
- name: serviceId
in: path
required: true
description: The ID of the Managed Service to access.
schema:
type: integer
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service View
description: |
Returns information about a single Managed Service on your Account.
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedService
x-linode-cli-action: service-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested Managed Service.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/services/9994
- lang: CLI
source: >
linode-cli managed service-view 9994
put:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service Update
description: |
Updates information about a Managed Service.
This command can only be accessed by the unrestricted users of an account.
operationId: updateManagedService
x-linode-cli-action: service-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
responses:
'200':
description: Service updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"service_type": "url",
"label": "prod-1",
"address": "https://example.org",
"timeout": 30,
"body": "it worked",
"consultation_group": "on-call",
"notes": "The service name is my-cool-application",
"credentials": [
9991
]
}' \
https://api.linode.com/v4/managed/services/9994
- lang: CLI
source: >
linode-cli managed service-update 9994 \
--service_type url \
--label prod-1 \
--address "https://example.org" \
--timeout 30 \
--body "it worked" \
--consultation_group on-call \
--notes "The service name is my-cool-application" \
--credentials 9991
delete:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service Delete
description: |
Deletes a Managed Service. This service will no longer be monitored by
Linode Managed.
This command can only be accessed by the unrestricted users of an account.
operationId: deleteManagedService
x-linode-cli-action: service-delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Service deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/managed/services/9994
- lang: CLI
source: >
linode-cli managed service-delete 9994
/managed/services/{serviceId}/disable:
parameters:
- name: serviceId
in: path
required: true
description: The ID of the Managed Service to disable.
schema:
type: integer
x-linode-cli-command: managed
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service Disable
description: |
Temporarily disables monitoring of a Managed Service.
This command can only be accessed by the unrestricted users of an account.
operationId: disableManagedService
x-linode-cli-action: service-disable
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Service disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/managed/services/9994/disable
- lang: CLI
source: >
linode-cli managed service-disable 9994
/managed/services/{serviceId}/enable:
parameters:
- name: serviceId
in: path
required: true
description: The ID of the Managed Service to enable.
schema:
type: integer
x-linode-cli-command: managed
post:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Service Enable
description: |
Enables monitoring of a Managed Service.
This command can only be accessed by the unrestricted users of an account.
operationId: enableManagedService
x-linode-cli-action: service-enable
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Service enabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ManagedService'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/managed/services/9994/enable
- lang: CLI
source: >
linode-cli managed service-enable 9994
/managed/stats:
x-linode-cli-command: managed
get:
x-linode-grant: unrestricted only
tags:
- Managed
summary: Managed Stats List
description: |
Returns a list of Managed Stats on your Account in the form of x and y data points.
You can use these data points to plot your own graph visualizations. These stats
reflect the last 24 hours of combined usage across all managed Linodes on your account
giving you a high-level snapshot of data for the following:
* cpu
* disk
* swap
* network in
* network out
This command can only be accessed by the unrestricted users of an account.
operationId: getManagedStats
x-linode-cli-action: stats-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A list of Managed Stats from the last 24 hours.
content:
application/json:
schema:
type: object
properties:
data:
type: object
oneOf:
- x-linode-ref-name: "Stats Available"
$ref: '#/components/schemas/StatsDataAvailable'
- x-linode-ref-name: "Stats Unavailable"
$ref: '#/components/schemas/StatsDataUnavailable'
discriminator:
propertyName: x-linode-ref-name
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/managed/stats
- lang: CLI
source: >
linode-cli managed stats-list
/networking/ips:
x-linode-cli-command: networking
get:
x-linode-grant: read_only
tags:
- Networking
summary: IP Addresses List
description: >
Returns a paginated list of IP Addresses on your Account, excluding
private addresses.
operationId: getIPs
x-linode-cli-action: ips-list
security:
- personalAccessToken: []
- oauth:
- ips:read_only
responses:
'200':
description: A paginated list of IP Addresses.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/IPAddress'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ips
- lang: CLI
source: >
linode-cli networking ips-list
post:
x-linode-grant: read_write
tags:
- Networking
summary: IP Address Allocate
description: >
Allocates a new IPv4 Address on your Account. The Linode must be
configured to support additional addresses - please
[open a support ticket](/docs/api/support/#support-ticket-open) requesting additional
addresses before attempting allocation.
operationId: allocateIP
x-linode-cli-action: ip-add
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: Information about the address you are creating.
required: true
content:
application/json:
schema:
required:
- type
- public
- linode_id
properties:
type:
type: string
enum:
- ipv4
description: >
The type of address you are requesting. Only
IPv4 addresses may be allocated through this endpoint.
example: ipv4
public:
type: boolean
description: >
Whether to create a public or private IPv4 address.
example: true
linode_id:
type: integer
description: >
The ID of a Linode you you have access to that this address
will be allocated to.
example: 123
responses:
'200':
description: IP Address allocated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "ipv4",
"public": true,
"linode_id": 123
}' \
https://api.linode.com/v4/networking/ips
- lang: CLI
source: >
linode-cli networking ip-add \
--type ipv4 \
--public true \
--linode_id 123
/networking/ips/{address}:
parameters:
- name: address
in: path
required: true
description: The address to operate on.
schema:
type: string
format: ip
x-linode-cli-command: networking
get:
x-linode-grant: read_only
tags:
- Networking
summary: IP Address View
description: >
Returns information about a single IP Address on your Account.
operationId: getIP
x-linode-cli-action: ip-view
security:
- personalAccessToken: []
- oauth:
- ips:read_only
responses:
'200':
description: The requested IP Address.
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ips/97.107.143.141
- lang: CLI
source: >
linode-cli networking ip-view 97.107.143.141
put:
x-linode-grant: read_write
tags:
- Networking
summary: IP Address RDNS Update
description: >
Sets RDNS on an IP Address. Forward DNS must already be set up for
reverse DNS to be applied. If you set the RDNS to `null` for public
IPv4 addresses, it will be reset to the default _ip.linodeusercontent.com_
RDNS value.
operationId: updateIP
x-linode-cli-action: ip-update
security:
- personalAccessToken: []
- oauth:
- ips:read_write
requestBody:
description: The information to update.
required: true
content:
application/json:
schema:
required:
- rdns
type: object
properties:
rdns:
type: string
description: >
The reverse DNS assigned to this address. For public IPv4 addresses,
this will be set to a default value provided by Linode if not
explicitly set.
x-linode-cli-display: 4
nullable: true
example: test.example.org
responses:
'200':
description: RDNS set successfully
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddress'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"rdns": "test.example.org"
}' \
https://api.linode.com/v4/networking/ips/97.107.143.141
- lang: CLI
source: >
linode-cli networking ip-update \
97.107.143.141 \
--rdns "test.example.org"
/networking/ips/assign:
x-linode-cli-command: networking
post:
x-linode-grant: read_write
tags:
- Networking
summary: IP Addresses Assign
description: |
Assign multiple IPv4 addresses and/or IPv6 ranges to multiple Linodes in one Region. This allows swapping, shuffling, or otherwise reorganizing IPs to your Linodes.
The following restrictions apply:
* All Linodes involved must have at least one public IPv4 address after assignment.
* Linodes may have no more than one assigned private IPv4 address.
* Linodes may have no more than one assigned IPv6 range.
[Open a Support Ticket](/docs/api/support/#support-ticket-open) to request additional IPv4 addresses or IPv6 ranges beyond standard account limits.
**Note**: Removing an IP address that has been set as a Managed Linode's `ssh.ip` causes the Managed Linode's SSH access settings to reset to their default values. To view and configure Managed Linode SSH settings, use the following commands:
* **Linode's Managed Settings View** ([GET /managed/linode-settings/{linodeId}](/docs/api/managed/#linodes-managed-settings-view))
* **Linode's Managed Settings Update** ([PUT /managed/linode-settings/{linodeId}](/docs/api/managed/#linodes-managed-settings-update))
operationId: assignIPs
x-linode-cli-action: ip-assign
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: >
Information about what IPv4 address or IPv6 range to assign, and to which Linode.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/IPAddressesAssignRequest"
responses:
'200':
description: All assignments completed successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"assignments": [
{
"address": "192.0.2.1",
"linode_id": 123
},
{
"address": "2001:db8:3c4d:15::/64",
"linode_id": 234
}
]
}' \
https://api.linode.com/v4/networking/ips/assign
- lang: CLI
source: >
linode-cli networking ip-assign \
--region us-east \
--assignments.address 192.0.2.1 \
--assignments.linode_id 123 \
--assignments.address 2001:db8:3c4d:15::/64 \
--assignments.linode_id 234
/networking/ips/share:
x-linode-cli-command: networking
post:
servers:
- url: https://api.linode.com/v4
- url: https://api.linode.com/v4beta
x-linode-grant: read_write
tags:
- Networking
summary: IP Addresses Share
description: |
Configure shared IPs.
IP sharing allows IP address reassignment (also referred to as IP failover) from one Linode to another if the primary Linode becomes unresponsive. This means that requests to the primary Linode's IP address can be automatically rerouted to secondary Linodes at the configured shared IP addresses.
IP failover requires configuration of a failover service (such as [Keepalived](/docs/guides/ip-failover-keepalived)) within the internal system of the primary Linode.
operationId: shareIPs
x-linode-cli-action: ip-share
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: Information about what IPs to share with which Linode.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddressesShareRequest'
responses:
'200':
description: IP Address sharing successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"ips": [
"192.0.2.1",
"2001:db8:3c4d:15::"
]
}' \
https://api.linode.com/v4/networking/ips/share
- lang: CLI
source: >
linode-cli networking ip-share \
--linode_id 123 \
--ips 192.0.2.1 \
--ips 2001:db8:3c4d:15::
/networking/ipv4/assign:
x-linode-cli-command: networking
post:
x-linode-grant: read_write
tags:
- Networking
summary: Linodes Assign IPv4s
description: |
This command is equivalent to **IP Addresses Assign** ([POST /networking/ips/assign](#ip-addresses-assign)).
Assign multiple IPv4 addresses and/or IPv6 ranges to multiple Linodes in one Region. This allows swapping, shuffling, or otherwise reorganizing IPs to your Linodes.
The following restrictions apply:
* All Linodes involved must have at least one public IPv4 address after assignment.
* Linodes may have no more than one assigned private IPv4 address.
* Linodes may have no more than one assigned IPv6 range.
[Open a Support Ticket](/docs/api/support/#support-ticket-open) to request additional IPv4 addresses or IPv6 ranges beyond standard account limits.
**Note**: Removing an IP address that has been set as a Managed Linode's `ssh.ip` causes the Managed Linode's SSH access settings to reset to their default values. To view and configure Managed Linode SSH settings, use the following commands:
* **Linode's Managed Settings View** ([GET /managed/linode-settings/{linodeId}](/docs/api/managed/#linodes-managed-settings-view))
* **Linode's Managed Settings Update** ([PUT /managed/linode-settings/{linodeId}](/docs/api/managed/#linodes-managed-settings-update))
operationId: assignIPv4s
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: >
Information about what IPv4 address to assign, and to which Linode.
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/IPAddressesAssignRequest"
responses:
'200':
description: All assignments completed successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"assignments": [
{
"address": "192.0.2.1",
"linode_id": 123
},
{
"address": "2001:db8:3c4d:15::/64",
"linode_id": 234
}
]
}' \
https://api.linode.com/v4/networking/ipv4/assign
- lang: CLI
source: >
linode-cli networking ip-assign \
--region us-east \
--assignments.address 192.0.2.1 \
--assignments.linode_id 123 \
--assignments.address 2001:db8:3c4d:15::/64 \
--assignments.linode_id 234
/networking/ipv4/share:
x-linode-cli-command: networking
post:
x-linode-grant: read_write
tags:
- Networking
summary: IPv4 Sharing Configure
description: |
This command is equivalent to **IP Addresses Share** ([POST /networking/ips/share](#ip-addresses-share)).
Configure shared IPs.
IP sharing allows IP address reassignment (also referred to as IP failover) from one Linode to another if the primary Linode becomes unresponsive. This means that requests to the primary Linode's IP address can be automatically rerouted to secondary Linodes at the configured shared IP addresses.
IP failover requires configuration of a failover service (such as [Keepalived](/docs/guides/ip-failover-keepalived)) within the internal system of the primary Linode.
operationId: shareIPv4s
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: Information about what IPs to share with which Linode.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IPAddressesShareRequest'
responses:
'200':
description: Sharing configured successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"ips": [
"192.0.2.1",
"192.0.2.2"
]
}' \
https://api.linode.com/v4/networking/ipv4/share
- lang: CLI
source: >
linode-cli networking ip-share \
--linode_id 123 \
--ips 192.0.2.1 \
--ips 192.0.2.2
/networking/ipv6/pools:
x-linode-cli-command: networking
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Networking
summary: IPv6 Pools List
description: >
Displays the IPv6 pools on your Account. A pool of IPv6 addresses are routed to all of your
Linodes in a single [Region](/docs/api/regions/#regions-list). Any Linode on your Account may bring up any address in this
pool at any time, with no external configuration required.
operationId: getIPv6Pools
x-linode-cli-action: v6-pools
security:
- personalAccessToken: []
- oauth:
- ips:read_only
responses:
'200':
description: The IPv6 pools on your Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/IPv6Pool'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ipv6/pools
- lang: CLI
source: >
linode-cli networking v6-pools
/networking/ipv6/ranges:
x-linode-cli-command: networking
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Networking
summary: IPv6 Ranges List
description: >
Displays the IPv6 ranges on your Account.
* An IPv6 range is a `/64` or `/54` block of IPv6 addresses routed to a single Linode in a given [Region](/docs/api/regions/#regions-list).
* Your Linode is responsible for routing individual addresses in the range, or handling traffic for all the addresses in the range.
* Access the IPv6 Range Create ([POST /networking/ipv6/ranges](/docs/api/networking/#ipv6-range-create)) endpoint to add a `/64` or `/56` block of IPv6 addresses to your account.
operationId: getIPv6Ranges
x-linode-cli-action: v6-ranges
security:
- personalAccessToken: []
- oauth:
- ips:read_only
responses:
'200':
description: The IPv6 ranges on your Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/IPv6Range'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/ipv6/ranges
- lang: CLI
source: >
linode-cli networking v6-ranges
post:
tags:
- Networking
summary: IPv6 Range Create
description: |
Creates an IPv6 Range and assigns it based on the provided Linode or route target IPv6 SLAAC address. See the `ipv6` property when accessing the Linode View ([GET /linode/instances/{linodeId}](/docs/api/linode-instances/#linode-view)) endpoint to view a Linode's IPv6 SLAAC address.
* Either `linode_id` or `route_target` is required in a request.
* `linode_id` and `route_target` are mutually exclusive. Submitting values for both properties in a request results in an error.
* Upon a successful request, an IPv6 range is created in the [Region](/docs/api/regions/#regions-list) that corresponds to the provided `linode_id` or `route_target`.
* Your Linode is responsible for routing individual addresses in the range, or handling traffic for all the addresses in the range.
* Access the IP Addresses Assign ([POST /networking/ips/assign](/docs/api/networking/#ip-addresses-assign)) endpoint to re-assign IPv6 Ranges to your Linodes.
**Note**: The following restrictions apply:
* A Linode can only have one IPv6 range targeting its SLAAC address.
* An account can only have one IPv6 range in each [Region](/docs/api/regions/#regions-list).
* [Open a Support Ticket](/docs/api/support/#support-ticket-open) to request expansion of these restrictions.
operationId: postIPv6Range
x-linode-cli-action: v6-range-create
security:
- personalAccessToken: []
- oauth:
- ips:read_write
- linodes:read_write
requestBody:
description: >
Information about the IPv6 range to create.
required: true
content:
application/json:
schema:
required:
- prefix_length
properties:
linode_id:
type: integer
description: |
The ID of the Linode to assign this range to. The SLAAC address for the provided Linode is used as the range's `route_target`.
* **Required** if `route_target` is omitted from the request.
* Mutually exclusive with `route_target`. Submitting values for both properties in a request results in an error.
example: 123
prefix_length:
type: integer
enum:
- 56
- 64
description: >
The prefix length of the IPv6 range.
route_target:
type: string
format: ipv6
description: |
The IPv6 SLAAC address to assign this range to.
* **Required** if `linode_id` is omitted from the request.
* Mutually exclusive with `linode_id`. Submitting values for both properties in a request results in an error.
* **Note**: Omit the `/128` prefix length of the SLAAC address when using this property.
example: 2001:0db8::1
responses:
'200':
description: IPv6 range created successfully.
content:
application/json:
schema:
type: object
properties:
range:
type: string
format: ipv6/prefix_length
description: >
The IPv6 network range, including subnet and prefix length.
example: 2001:0db8::/64
route_target:
type: string
format: ipv6
description: >
The route target IPV6 SLAAC address for this range. Does not include the prefix length.
example: 2001:0db8::1
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 123,
"prefix_length": 64
}' \
https://api.linode.com/v4/networking/ipv6/ranges
- lang: CLI
source: >
linode-cli networking v6-range-create \
--linode_id 123 \
--prefix_length 64
/networking/ipv6/ranges/{range}:
parameters:
- name: range
in: path
description: |
The IPv6 range to access. Corresponds to the `range` property of objects returned from the IPv6 Ranges List ([GET /networking/ipv6/ranges](/docs/api/networking/#ipv6-ranges-list)) command.
**Note**: Omit the prefix length of the IPv6 range.
required: true
schema:
type: string
format: ipv6
x-linode-cli-command: networking
get:
tags:
- Networking
summary: IPv6 Range View
description: |
View IPv6 range information.
operationId: getIPv6Range
x-linode-cli-action: v6-range-view
security:
- personalAccessToken: []
- oauth:
- ips:read
responses:
'200':
description: Returns IPv6 range information.
content:
application/json:
schema:
$ref: '#/components/schemas/IPv6RangeBGP'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" https://api.linode.com/v4/networking/ipv6/ranges/2001:0db8::
- lang: CLI
source: >
linode-cli networking v6-range-view 2001:0db8::
delete:
tags:
- Networking
summary: IPv6 Range Delete
description: |
Removes this IPv6 range from your account and disconnects the range from any assigned Linodes.
**Note:** Shared IPv6 ranges cannot be deleted at this time. Please contact Customer Support for assistance.
operationId: deleteIPv6Range
x-linode-cli-action: v6-range-delete
security:
- personalAccessToken: []
- oauth:
- ips:read_write
responses:
'200':
description: IPv6 Range deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/ipv6/ranges/2001:0db8::
- lang: CLI
source: >
linode-cli networking v6-range-delete 2001:0db8::
/networking/firewalls:
x-linode-cli-command: firewalls
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewalls List
description: |
Returns a paginated list of accessible Firewalls.
operationId: getFirewalls
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- firewall:read_only
responses:
'200':
description: Returns an array of Firewalls.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Firewall'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls
- lang: CLI
source: >
linode-cli firewalls list
post:
x-linode-grant: add_firewalls
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Create
description: |
Creates a Firewall to filter network traffic.
* Use the `rules` property to create inbound and outbound access rules.
* Use the `devices` property to assign the Firewall to a service and apply its Rules to the device. Requires `read_write` [User's Grants](/docs/api/account/#users-grants-view) to the device.
Currently, Firewalls can only be assigned to Linode instances.
* A Firewall can be assigned to multiple Linode instances at a time.
* A Linode instance can have one active, assigned Firewall at a time.
Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if another active Firewall is already assigned to the same service.
* A `firewall_create` Event is generated when this endpoint returns successfully.
operationId: createFirewalls
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
requestBody:
description: Creates a Firewall object that can be applied to a Linode service to filter the service's network traffic.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Firewall'
required:
- label
- rules
properties:
devices:
type: object
description: |
Devices to create for this Firewall.
When a Device is created, the Firewall is assigned to its associated service.
Currently, Devices can only be created for Linode instances.
properties:
linodes:
description: >
An array of Linode IDs. A Firewall Device is created for each ID.
type: array
items:
type: integer
example:
- 123
- 456
rules:
required:
- inbound_policy
- outbound_policy
properties:
inbound:
required:
- action
- addresses
- protocol
outbound:
required:
- action
- addresses
- protocol
responses:
'200':
description: Returns information about the created Firewall.
content:
application/json:
schema:
$ref: '#/components/schemas/Firewall'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "firewall123",
"rules": {
"inbound_policy": "DROP",
"inbound": [
{
"protocol": "TCP",
"ports": "22, 80, 443",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "inbound-rule123",
"description": "An example inbound rule description."
}
],
"outbound_policy": "DROP",
"outbound": [
{
"protocol": "TCP",
"ports": "49152-65535",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "outbound-rule123",
"description": "An example outbound rule description."
}
]
},
"devices": {
"linodes": [
123
]
},
"tags": [
"example tag",
"another example"
]
}' \
https://api.linode.com/v4/networking/firewalls
- lang: CLI
source: >
linode-cli firewalls create \
--label example-firewall \
--rules.outbound_policy ACCEPT \
--rules.inbound_policy DROP \
--rules.inbound '[{"protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.1", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}, "action": "ACCEPT"}]' \
--rules.outbound '[{"protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.0/24"],"ipv6": ["2001:DB8::/32"]}, "action": "DROP", "label": "outbound-rule123", "description": "An example outbound rule description."}]'
/networking/firewalls/{firewallId}:
parameters:
- name: firewallId
in: path
description: >
ID of the Firewall to access.
required: true
schema:
type: integer
x-linode-cli-command: firewalls
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall View
operationId: getFirewall
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- firewall:read_only
description: |
Get a specific Firewall resource by its ID. The Firewall's Devices will not be
returned in the response. Instead, use the
[List Firewall Devices](/docs/api/networking/#firewall-devices-list)
endpoint to review them.
responses:
'200':
description: Returns information about this Firewall.
content:
application/json:
schema:
$ref: '#/components/schemas/Firewall'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123
- lang: CLI
source: >
linode-cli firewalls view 123
put:
x-linode-grant: read_write
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Update
description: |
Updates information for a Firewall. Some parts of a Firewall's configuration cannot
be manipulated by this endpoint:
- A Firewall's Devices cannot be set with this endpoint. Instead, use the
[Create Firewall Device](/docs/api/networking/#firewall-device-create)
and [Delete Firewall Device](/docs/api/networking/#firewall-device-delete)
endpoints to assign and remove this Firewall from Linode services.
- A Firewall's Rules cannot be changed with this endpoint. Instead, use the
[Update Firewall Rules](/docs/api/networking/#firewall-rules-update)
endpoint to update your Rules.
- A Firewall's status can be set to `enabled` or `disabled` by this endpoint, but it cannot be
set to `deleted`. Instead, use the
[Delete Firewall](/docs/api/networking/#firewall-delete)
endpoint to delete a Firewall.
If a Firewall's status is changed with this endpoint, a corresponding `firewall_enable` or
`firewall_disable` Event will be generated.
operationId: updateFirewall
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
requestBody:
description: The Firewall information to update.
content:
application/json:
schema:
type: object
properties:
tags:
$ref: '#/components/schemas/Firewall/properties/tags'
label:
$ref: '#/components/schemas/Firewall/properties/label'
status:
type: string
description: >
The status to be applied to this Firewall.
* When a Firewall is first created its status is `enabled`.
* Use the [Delete Firewall](/docs/api/networking/#firewall-delete) endpoint to delete a Firewall.
enum:
- enabled
- disabled
example: enabled
x-linode-cli-display: 3
responses:
'200':
description: Firewall updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Firewall'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"status": "disabled"
}' \
https://api.linode.com/v4/networking/firewalls/123
- lang: CLI
source: >
linode-cli firewalls update 123 \
--status disabled
delete:
x-linode-grant: read_write
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Delete
operationId: deleteFirewall
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
description: |
Delete a Firewall resource by its ID. This will remove all of the Firewall's Rules
from any Linode services that the Firewall was assigned to.
A `firewall_delete` Event is generated when this endpoint returns successfully.
responses:
'200':
description: Delete Successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/firewalls/123
- lang: CLI
source: >
linode-cli firewalls delete 123
/networking/firewalls/{firewallId}/devices:
parameters:
- name: firewallId
in: path
description: >
ID of the Firewall to access.
required: true
schema:
type: integer
x-linode-cli-command: firewalls
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4
tags:
- Networking
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: Firewall Devices List
description: |
Returns a paginated list of a Firewall's Devices. A Firewall Device assigns a
Firewall to a Linode service (referred to as the Device's `entity`). Currently,
only Devices with an entity of type `linode` are accepted.
operationId: getFirewallDevices
x-linode-cli-action: devices-list
security:
- personalAccessToken: []
- oauth:
- firewall:read_only
responses:
'200':
description: A paginated list of Firewall Devices
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/FirewallDevices'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/devices
- lang: CLI
source: >
linode-cli firewalls devices-list 123
post:
x-linode-grant: read_write
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Device Create
description: |
Creates a Firewall Device, which assigns a Firewall to a service (referred to
as the Device's `entity`) and applies the Firewall's Rules to the device.
* Currently, only Devices with an entity of type `linode` are accepted.
* A Firewall can be assigned to multiple Linode instances at a time.
* A Linode instance can have one active, assigned Firewall at a time.
Additional disabled Firewalls can be assigned to a service, but they cannot be enabled if another active Firewall is already assigned to the same service.
* A `firewall_device_add` Event is generated when the Firewall Device is added successfully.
operationId: createFirewallDevice
x-linode-cli-action: device-create
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
requestBody:
content:
application/json:
schema:
type: object
required:
- id
- type
allOf:
- $ref: '#/components/schemas/FirewallDevices/properties/entity'
responses:
'200':
description: Returns information about the created Firewall Device.
content:
application/json:
schema:
$ref: '#/components/schemas/FirewallDevices'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"type": "linode",
"id": 123
}' \
https://api.linode.com/v4/networking/firewalls/123/devices
- lang: CLI
source: >
linode-cli firewalls device-create 123 \
--id 456 \
--type "linode"
/networking/firewalls/{firewallId}/devices/{deviceId}:
parameters:
- name: firewallId
in: path
description: >
ID of the Firewall to access.
required: true
schema:
type: integer
- name: deviceId
in: path
description: >
ID of the Firewall Device to access.
required: true
schema:
type: integer
x-linode-cli-command: firewalls
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Device View
description: |
Returns information for a Firewall Device, which assigns a Firewall
to a Linode service (referred to as the Device's `entity`). Currently,
only Devices with an entity of type `linode` are accepted.
operationId: getFirewallDevice
x-linode-cli-action: device-view
security:
- personalAccessToken: []
- oauth:
- firewall:read_only
responses:
'200':
description: The requested Firewall Device.
content:
application/json:
schema:
$ref: '#/components/schemas/FirewallDevices'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/devices/456
- lang: CLI
source: >
linode-cli firewalls device-view \
123 456
delete:
x-linode-grant: read_write
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Device Delete
operationId: deleteFirewallDevice
x-linode-cli-action: device-delete
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
description: |
Removes a Firewall Device, which removes a Firewall from the Linode service it was
assigned to by the Device. This will remove all of the Firewall's Rules from the Linode
service. If any other Firewalls have been assigned to the Linode service, then those Rules
will remain in effect.
A `firewall_device_remove` Event is generated when the Firewall Device is removed successfully.
responses:
'200':
description: Delete Successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/networking/firewalls/123/devices/456
- lang: CLI
source: >
linode-cli firewalls device-delete 123 456
/networking/firewalls/{firewallId}/rules:
parameters:
- name: firewallId
in: path
description: >
ID of the Firewall to access.
required: true
schema:
type: integer
x-linode-cli-command: firewalls
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Rules List
description: |
Returns the inbound and outbound Rules for a Firewall.
operationId: getFirewallRules
x-linode-cli-action: rules-list
security:
- personalAccessToken: []
- oauth:
- firewall:read_only
responses:
'200':
description: The requested Firewall Rules.
content:
application/json:
schema:
$ref: '#/components/schemas/Firewall/properties/rules'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/networking/firewalls/123/rules
- lang: CLI
source: >
linode-cli firewalls rules-list 123
put:
x-linode-grant: read_write
servers:
- url: https://api.linode.com/v4
tags:
- Networking
summary: Firewall Rules Update
description: |
Updates the inbound and outbound Rules for a Firewall.
**Note:** This command replaces all of a Firewall's `inbound` and/or `outbound` rulesets with the values specified in your request.
operationId: updateFirewallRules
x-linode-cli-action: rules-update
security:
- personalAccessToken: []
- oauth:
- firewall:read_write
requestBody:
description: The Firewall Rules information to update.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Firewall/properties/rules'
properties:
inbound:
required:
- action
- addresses
- protocol
outbound:
required:
- action
- addresses
- protocol
responses:
'200':
description: Firewall Rules updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Firewall/properties/rules'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"inbound_policy": "DROP",
"inbound": [
{
"protocol": "TCP",
"ports": "22, 80, 443",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "inbound-rule123",
"description": "An example inbound rule description."
}
],
"outbound_policy": "DROP",
"outbound": [
{
"protocol": "TCP",
"ports": "49152-65535",
"addresses": {
"ipv4": [
"192.0.2.0/24"
],
"ipv6": [
"2001:DB8::/32"
]
},
"action": "ACCEPT",
"label": "outbound-rule123",
"description": "An example outbound rule description."
}
]
}' \
https://api.linode.com/v4/networking/firewalls/123/rules
- lang: CLI
source: >
linode-cli firewalls rules-update 123 \
--inbound '[{"action":"ACCEPT", "protocol": "TCP", "ports": "22, 80, 8080, 443", "addresses": {"ipv4": ["192.0.2.1/32", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]' \
--outbound '[{"action":"DROP","protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.1/32", "192.0.2.0/24"], "ipv6": ["2001:DB8::/32"]}}]'
/networking/vlans:
x-linode-cli-command: vlans
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4beta
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Networking
summary: VLANs List
description: |
Returns a list of all Virtual Local Area Networks (VLANs) on your Account. VLANs provide
a mechanism for secure communication between two or more Linodes that are assigned to the
same VLAN and are both within the same Layer 2 broadcast domain.
VLANs are created and attached to Linodes by using the `interfaces` property for the following endpoints:
- Linode Create ([POST /linode/instances](/docs/api/linode-instances/#linode-create))
- Configuration Profile Create ([POST /linode/instances/{linodeId}/configs](/docs/api/linode-instances/#configuration-profile-create))
- Configuration Profile Update ([PUT /linode/instances/{linodeId}/configs/{configId}](/docs/api/linode-instances/#configuration-profile-update))
There are several ways to detach a VLAN from a Linode:
- [Update](/docs/api/linode-instances/#configuration-profile-update) the active Configuration Profile to remove the VLAN interface, then [reboot](/docs/api/linode-instances/#linode-reboot) the Linode.
- [Create](/docs/api/linode-instances/#configuration-profile-create) a new Configuration Profile without the VLAN interface, then [reboot](/docs/api/linode-instances/#linode-reboot) the Linode into the new Configuration Profile.
- [Delete](/docs/api/linode-instances/#linode-delete) the Linode.
**Note:** Only Next Generation Network (NGN) data centers support VLANs. Use the Regions ([/regions](/docs/api/regions/)) endpoint to view the capabilities of data center regions.
If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center,
the migration or cloning will not initiate. If a Linode cannot be migrated because of an incompatibility,
you will be prompted to select a different data center or contact support.
**Note:** See our guide on [Getting Started with VLANs](/docs/guides/getting-started-with-vlans/) to view additional [limitations](/docs/guides/getting-started-with-vlans/#limitations).
operationId: getVLANs
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- linodes:read_only
responses:
'200':
description: The VLANs available on this Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Vlans'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4beta/networking/vlans/
- lang: CLI
source: >
linode-cli networking vlans-list
/nodebalancers:
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: NodeBalancers List
description: >
Returns a paginated list of NodeBalancers you have access to.
operationId: getNodeBalancers
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: A paginated list of NodeBalancers.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NodeBalancer'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers
- lang: CLI
source: >
linode-cli nodebalancers list
post:
x-linode-grant: add_nodebalancers
tags:
- NodeBalancers
summary: NodeBalancer Create
description: |
Creates a NodeBalancer in the requested Region.
NodeBalancers require a port Config with at least one backend Node to start serving requests.
When using the Linode CLI to create a NodeBalancer, first create a NodeBalancer without any Configs. Then, create Configs and Nodes for that NodeBalancer with the respective [Config Create](/docs/api/nodebalancers/#config-create) and [Node Create](/docs/api/nodebalancers/#node-create) commands.
operationId: createNodeBalancer
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: Information about the NodeBalancer to create.
required: true
x-linode-cli-allowed-defaults:
- region
content:
application/json:
schema:
required:
- region
properties:
region:
type: string
description: >
The ID of the Region to create this NodeBalancer in.
example: us-east
label:
$ref: '#/components/schemas/NodeBalancer/properties/label'
client_conn_throttle:
$ref: '#/components/schemas/NodeBalancer/properties/client_conn_throttle'
configs:
type: array
description: |
The port Config(s) to create for this NodeBalancer.
Each Config must have a unique port and at least one Node.
required:
- nodes
items:
type: object
description: A request object representing a NodeBalancer Config, including Nodes.
properties:
port:
$ref: '#/components/schemas/NodeBalancerConfig/properties/port'
protocol:
$ref: '#/components/schemas/NodeBalancerConfig/properties/protocol'
algorithm:
$ref: '#/components/schemas/NodeBalancerConfig/properties/algorithm'
stickiness:
$ref: '#/components/schemas/NodeBalancerConfig/properties/stickiness'
check:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check'
check_interval:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_interval'
check_timeout:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_timeout'
check_attempts:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_attempts'
check_path:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_path'
check_body:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_body'
check_passive:
$ref: '#/components/schemas/NodeBalancerConfig/properties/check_passive'
proxy_protocol:
$ref: '#/components/schemas/NodeBalancerConfig/properties/proxy_protocol'
cipher_suite:
$ref: '#/components/schemas/NodeBalancerConfig/properties/cipher_suite'
ssl_cert:
$ref: '#/components/schemas/NodeBalancerConfig/properties/ssl_cert'
ssl_key:
$ref: '#/components/schemas/NodeBalancerConfig/properties/ssl_key'
nodes:
type: array
description: |
The NodeBalancer Node(s) that serve this Config.
items:
$ref: '#/components/schemas/NodeBalancerNode'
responses:
'200':
description: NodeBalancer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"region": "us-east",
"label": "balancer12345",
"client_conn_throttle": 0,
"configs": [
{
"port": 443,
"protocol": "https",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "none",
"cipher_suite": "recommended",
"ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
"ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
"nodes": [
{
"address": "192.168.210.120:80",
"label": "node1",
"weight": 50,
"mode": "accept"
},
{
"address": "192.168.210.122:81",
"label": "node2",
"weight": 50,
"mode": "accept"
}
]
}
]
}' \
https://api.linode.com/v4/nodebalancers
- lang: CLI
source: >
linode-cli nodebalancers create \
--region us-east \
--label balancer12345 \
--client_conn_throttle 0
/nodebalancers/{nodeBalancerId}:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
summary: NodeBalancer View
description: >
Returns a single NodeBalancer you can access.
operationId: getNodeBalancer
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: The requested NodeBalancer object.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers/12345
- lang: CLI
source: >
linode-cli nodebalancers view 12345
put:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: NodeBalancer Update
description: >
Updates information about a NodeBalancer you can access.
operationId: updateNodeBalancer
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: The information to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancer'
responses:
'200':
description: NodeBalancer updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancer'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "balancer12345",
"client_conn_throttle": 0
}' \
https://api.linode.com/v4/nodebalancers/12345
- lang: CLI
source: >
linode-cli nodebalancers update 12345 \
--label balancer12345 \
--client_conn_throttle 0
delete:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: NodeBalancer Delete
description: >
Deletes a NodeBalancer.
**This is a destructive action and cannot be undone.**
Deleting a NodeBalancer will also delete all associated Configs and Nodes,
although the backend servers represented by the Nodes will not be
changed or removed. Deleting a NodeBalancer will cause you to lose access
to the IP Addresses assigned to this NodeBalancer.
operationId: deleteNodeBalancer
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
responses:
'200':
description: NodeBalancer deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/nodebalancers/12345
- lang: CLI
source: >
linode-cli nodebalancers delete 12345
/nodebalancers/{nodeBalancerId}/configs:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: Configs List
description: >
Returns a paginated list of NodeBalancer Configs associated
with this NodeBalancer. NodeBalancer Configs represent
individual ports that this NodeBalancer will accept traffic
on, one Config per port.
For example, if you wanted to accept standard HTTP traffic, you would
need a Config listening on port 80.
operationId: getNodeBalancerConfigs
x-linode-cli-action: configs-list
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: A paginted list of NodeBalancer Configs
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NodeBalancerConfig'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers/12345/configs
- lang: CLI
source: >
linode-cli nodebalancers configs-list 12345
post:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Config Create
description: >
Creates a NodeBalancer Config, which allows the NodeBalancer to
accept traffic on a new port. You will need to add NodeBalancer Nodes
to the new Config before it can actually serve requests.
operationId: createNodeBalancerConfig
x-linode-cli-action: config-create
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: Information about the port to configure.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
responses:
'200':
description: Config created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"port": 443,
"protocol": "https",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "none",
"ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
"ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
"cipher_suite": "recommended"
}' \
https://api.linode.com/v4/nodebalancers/12345/configs
- lang: CLI
source: >
linode-cli nodebalancers config-create 12345 \
--port 443 \
--protocol https \
--algorithm roundrobin \
--stickiness http_cookie \
--check http_body \
--check_interval 90 \
--check_timeout 10 \
--check_attempts 3 \
--check_path "/test" \
--check_body "it works" \
--check_passive true \
--proxy_protocol "none" \
--ssl_cert "-----BEGIN CERTIFICATE-----
CERTIFICATE_INFORMATION
-----END CERTIFICATE-----" \
--ssl_key "-----BEGIN PRIVATE KEY-----
PRIVATE_KEY_INFORMATION
-----END PRIVATE KEY-----" \
--cipher_suite recommended
/nodebalancers/{nodeBalancerId}/configs/{configId}:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
- name: configId
in: path
description: The ID of the config to access.
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
summary: Config View
description: >
Returns configuration information for a single port of this
NodeBalancer.
operationId: getNodeBalancerConfig
x-linode-cli-action: config-view
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: The requested NodeBalancer config.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers/12345/configs/4567
- lang: CLI
source: >
linode-cli nodebalancers config-view \
12345 4567
put:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Config Update
description: >
Updates the configuration for a single port on a NodeBalancer.
operationId: updateNodeBalancerConfig
x-linode-cli-action: config-update
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
responses:
'200':
description: Config updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"port": 443,
"protocol": "https",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "none",
"ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
"ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
"cipher_suite": "recommended"
}' \
https://api.linode.com/v4/nodebalancers/12345/configs/4567
- lang: CLI
source: >
linode-cli nodebalancers config-update \
12345 4567 \
--port 443 \
--protocol https \
--algorithm roundrobin \
--stickiness http_cookie \
--check http_body \
--check_interval 90 \
--check_timeout 10 \
--check_attempts 3 \
--check_path "/test" \
--check_body "it works" \
--check_passive true \
--proxy_protocol "none" \
--ssl_cert "-----BEGIN CERTIFICATE-----
CERTIFICATE_INFORMATION
-----END CERTIFICATE-----" \
--ssl_key "-----BEGIN PRIVATE KEY-----
PRIVATE_KEY_INFORMATION
-----END PRIVATE KEY-----" \
--cipher_suite recommended
delete:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Config Delete
description: >
Deletes the Config for a port of this NodeBalancer.
**This cannot be undone.**
Once completed, this NodeBalancer will no longer
respond to requests on the given port. This also deletes all
associated NodeBalancerNodes, but the Linodes they were routing
traffic to will be unchanged and will not be removed.
operationId: deleteNodeBalancerConfig
x-linode-cli-action: config-delete
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
responses:
'200':
description: NodeBalancer Config deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/nodebalancers/12345/configs/4567
- lang: CLI
source: >
linode-cli nodebalancers config-delete \
12345 4567
/nodebalancers/{nodeBalancerId}/configs/{configId}/rebuild:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
- name: configId
in: path
description: The ID of the Config to access.
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
post:
x-linode-grant: add_nodebalancers
tags:
- NodeBalancers
summary: Config Rebuild
description: |
Rebuilds a NodeBalancer Config and its Nodes that you have permission to modify.
Use this command to update a NodeBalancer's Config and Nodes with a single request.
operationId: rebuildNodeBalancerConfig
x-linode-cli-action: config-rebuild
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: >
Information about the NodeBalancer Config to rebuild.
required: true
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/NodeBalancerConfig"
- type: object
required:
- nodes
properties:
nodes:
type: array
description: |
The NodeBalancer Node(s) that serve this Config.
Some considerations for Nodes when rebuilding a config:
* Current Nodes excluded from the request body will be deleted from the Config.
* Current Nodes (identified by their Node ID) will be updated.
* New Nodes (included without a Node ID) will be created.
items:
type: object
description: NodeBalancer Node request object including ID.
properties:
id:
type: integer
description: The unique ID of the Node to update.
example: 54321
address:
$ref: '#/components/schemas/NodeBalancerNode/properties/address'
label:
$ref: '#/components/schemas/NodeBalancerNode/properties/label'
weight:
$ref: '#/components/schemas/NodeBalancerNode/properties/weight'
mode:
$ref: '#/components/schemas/NodeBalancerNode/properties/mode'
responses:
'200':
description: NodeBalancer created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerConfig'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"port": 1234,
"protocol": "https",
"algorithm": "roundrobin",
"stickiness": "http_cookie",
"check": "http_body",
"check_interval": 90,
"check_timeout": 10,
"check_attempts": 3,
"check_path": "/test",
"check_body": "it works",
"check_passive": true,
"proxy_protocol": "none",
"cipher_suite": "recommended",
"ssl_cert": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
"ssl_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----",
"nodes": [
{
"id": 54321,
"address": "192.168.210.120:80",
"label": "node1",
"weight": 50,
"mode": "accept"
},
{
"address": "192.168.210.122:81",
"label": "node2",
"weight": 50,
"mode": "accept"
}
]
}' \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/rebuild
- lang: CLI
source: >
linode-cli nodebalancers config-rebuild \
12345 4567 \
--port 443 \
--protocol https \
--algorithm roundrobin \
--stickiness http_cookie \
--check http_body \
--check_interval 90 \
--check_timeout 10 \
--check_attempts 3 \
--check_path "/test" \
--check_body "it works" \
--check_passive true \
--proxy_protocol "none" \
--ssl_cert "-----BEGIN CERTIFICATE-----
CERTIFICATE_INFORMATION
-----END CERTIFICATE-----" \
--ssl_key "-----BEGIN PRIVATE KEY-----
PRIVATE_KEY_INFORMATION
-----END PRIVATE KEY-----" \
--cipher_suite recommended \
--nodes '{"address":"192.168.210.120:80","label":"node1","weight":50,"mode":"accept"}' \
--nodes '{"address":"192.168.210.122:80","label":"node2","weight":50,"mode":"accept"}'
/nodebalancers/{nodeBalancerId}/configs/{configId}/nodes:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
- name: configId
in: path
description: The ID of the NodeBalancer config to access.
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: Nodes List
description: >
Returns a paginated list of NodeBalancer nodes associated with
this Config. These are the backends that will be sent traffic
for this port.
operationId: getNodeBalancerConfigNodes
x-linode-cli-action: nodes-list
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: A paginated list of NodeBalancer nodes.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/NodeBalancerNode'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes
- lang: CLI
source: >
linode-cli nodebalancers nodes-list 12345 4567
post:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Node Create
description: >
Creates a NodeBalancer Node, a backend that can accept
traffic for this NodeBalancer Config. Nodes are routed
requests on the configured port based on their status.
operationId: createNodeBalancerNode
x-linode-cli-action: node-create
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: Information about the Node to create.
required: true
content:
application/json:
schema:
required:
- label
- address
allOf:
- $ref: '#/components/schemas/NodeBalancerNode'
responses:
'200':
description: Node created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerNode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"address": "192.168.210.120:80",
"label": "node54321",
"weight": 50,
"mode": "accept"
}' \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes
- lang: CLI
source: >
linode-cli nodebalancers node-create \
12345 4567 \
--address 192.168.210.120:80 \
--label node54321 \
--weight 50 \
--mode accept
/nodebalancers/{nodeBalancerId}/configs/{configId}/nodes/{nodeId}:
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
- name: configId
in: path
description: The ID of the Config to access
required: true
schema:
type: integer
- name: nodeId
in: path
description: The ID of the Node to access
required: true
schema:
type: integer
x-linode-cli-command: nodebalancers
get:
x-linode-grant: read_only
tags:
- NodeBalancers
summary: Node View
description: >
Returns information about a single Node, a backend for this
NodeBalancer's configured port.
operationId: getNodeBalancerNode
x-linode-cli-action: node-view
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
responses:
'200':
description: A paginated list of NodeBalancer nodes.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerNode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes/54321
- lang: CLI
source: >
linode-cli nodebalancers node-view 12345 4567 54321
put:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Node Update
description: >
Updates information about a Node, a backend for this NodeBalancer's
configured port.
operationId: updateNodeBalancerNode
x-linode-cli-action: node-update
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerNode'
responses:
'200':
description: Node updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerNode'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"address": "192.168.210.120:80",
"label": "node54321",
"weight": 50,
"mode": "accept"
}' \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes/54321
- lang: CLI
source: >
linode-cli nodebalancers node-create \
12345 4567 54321 \
--address 192.168.210.120:80 \
--label node54321 \
--weight 50 \
--mode accept
delete:
x-linode-grant: read_write
tags:
- NodeBalancers
summary: Node Delete
description: >
Deletes a Node from this Config. This backend will no longer
receive traffic for the configured port of this NodeBalancer.
This does not change or remove the Linode whose address was
used in the creation of this Node.
operationId: deleteNodeBalancerConfigNode
x-linode-cli-action: node-delete
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_write
responses:
'200':
description: Node deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes/54321
- lang: CLI
source: >
linode-cli nodebalancers node-delete \
12345 4567 54321
/nodebalancers/{nodeBalancerId}/stats:
x-linode-cli-command: nodebalancers
parameters:
- name: nodeBalancerId
in: path
description: The ID of the NodeBalancer to access.
required: true
schema:
type: integer
get:
x-linode-grant: read_only
tags:
- NodeBalancers
summary: NodeBalancer Statistics View
description: >
Returns detailed statistics about the requested NodeBalancer.
x-linode-cli-action: stats
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- nodebalancers:read_only
responses:
'200':
description: The requested stats.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeBalancerStats'
default:
$ref: '#/components/responses/ErrorResponse'
/object-storage/buckets:
get:
operationId: getObjectStorageBuckets
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Buckets List
description: |
Returns a paginated list of all Object Storage Buckets that you own.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/serviceops/#list-buckets) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: A paginated list of buckets you own.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObjectStorageBucket'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/
post:
operationId: createObjectStorageBucket
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket Create
description: |
Creates an Object Storage Bucket in the cluster specified. If the
bucket already exists and is owned by you, this endpoint will return a
`200` response with that bucket as if it had just been created.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#put-bucket) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: >
Information about the bucket you want to create.
content:
application/json:
schema:
type: object
required:
- label
- cluster
properties:
label:
type: string
description: >
The name for this bucket. Must be unique in the cluster you
are creating the bucket in, or an error will be returned. Labels will be
reserved only for the cluster that active buckets are created and stored in.
If you want to reserve this bucket's label in another cluster,
you must create a new bucket with the same label in the new cluster.
pattern: ^[a-z0-09][a-z0-9-]*[a-z0-9]?$
example: example-bucket
cluster:
type: string
description: >
The ID of the Object Storage Cluster where this bucket should
be created.
example: us-east-1
cors_enabled:
type: boolean
description: >
If true, the bucket will be created with CORS enabled for all
origins. For more fine-grained controls of CORS, use the S3
API directly.
example: true
default: false
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
description: >
The Access Control Level of the bucket using a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
default: private
example: private
responses:
'200':
description: The bucket created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageBucket'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "example-bucket",
"cluster": "us-east-1",
"cors_enabled": true,
"acl": "private"
}' \
https://api.linode.com/v4/object-storage/buckets/
/object-storage/buckets/{clusterId}/{bucket}:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
get:
operationId: getObjectStorageBucket
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket View
description: |
Returns a single Object Storage Bucket.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#get-bucket) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: The requested bucket.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageBucket'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket
delete:
operationId: deleteObjectStorageBucket
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket Remove
description: |
Removes a single bucket.
Bucket objects must be removed prior to removing the bucket. While buckets containing objects _may_ be
deleted using the [s3cmd command-line tool](/docs/products/storage/object-storage/guides/s3cmd/#delete-a-bucket), such operations
can fail if the bucket contains too many objects. The recommended
way to empty large buckets is to use the [S3 API to configure lifecycle policies](https://docs.ceph.com/en/latest/radosgw/bucketpolicy/#) that
remove all objects, then delete the bucket.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#delete-bucket) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
responses:
'200':
description: Bucket deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket
/object-storage/buckets/{clusterId}:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
get:
operationId: getObjectStorageBucketinCluster
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Buckets in Cluster List
description: |
Returns a list of Buckets in this cluster belonging to this Account.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#get-bucket) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: A paginated list of buckets you own in this cluster.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObjectStorageBucket'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/us-east-1
/object-storage/buckets/{clusterId}/{bucket}/access:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
post:
operationId: modifyObjectStorageBucketAccess
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket Access Modify
description: |
Allows changing basic Cross-origin Resource Sharing (CORS) and Access Control Level (ACL) settings.
Only allows enabling/disabling CORS for all origins, and/or setting canned ACLs.
For more fine-grained control of both systems, please use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#put-bucket-acl) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: The changes to make to the bucket's access controls.
content:
application/json:
schema:
properties:
cors_enabled:
type: boolean
description: >
If true, the bucket will be created with CORS enabled for all
origins. For more fine-grained controls of CORS, use the S3
API directly.
example: true
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
- custom
description: >
The Access Control Level of the bucket, as a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
example: private
responses:
'200':
description: Access controls updated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"cors_enabled": true,
"acl": "private"
}' \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/access
put:
operationId: updateObjectStorageBucketAccess
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket Access Update
description: |
Allows changing basic Cross-origin Resource Sharing (CORS) and Access Control Level (ACL) settings.
Only allows enabling/disabling CORS for all origins, and/or setting canned ACLs.
For more fine-grained control of both systems, please use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/bucketops/#put-bucket-acl) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: The changes to make to the bucket's access controls.
content:
application/json:
schema:
properties:
cors_enabled:
type: boolean
description: >
If true, the bucket will be created with CORS enabled for all
origins. For more fine-grained controls of CORS, use the S3
API directly.
example: true
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
- custom
description: >
The Access Control Level of the bucket, as a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
example: private
responses:
'200':
description: Access controls updated.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"cors_enabled": true,
"acl": "private"
}' \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/access
/object-storage/buckets/{clusterId}/{bucket}/object-acl:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
get:
operationId: viewObjectStorageBucketACL
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Object ACL Config View
description: |
View an Object's configured Access Control List (ACL) in this Object Storage bucket.
ACLs define who can access your buckets and objects and specify the level of access
granted to those users.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/objectops/#get-object-acl) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
parameters:
- name: name
in: query
required: true
description: >
The `name` of the object for which to retrieve its Access Control List (ACL).
Use the [Object Storage Bucket Contents List](/docs/api/object-storage/#object-storage-bucket-contents-list)
endpoint to access all object names in a bucket.
schema:
type: string
responses:
'200':
description: The Object's canned ACL and policy.
content:
application/json:
schema:
type: object
properties:
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
- custom
description: >
The Access Control Level of the bucket, as a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
example: public-read
acl_xml:
type: string
description: >
The full XML of the object's ACL policy.
example: "<AccessControlPolicy>...</AccessControlPolicy>"
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-acl?name=example.txt
put:
operationId: updateObjectStorageBucketACL
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Object ACL Config Update
description: |
Update an Object's configured Access Control List (ACL) in this Object Storage bucket.
ACLs define who can access your buckets and objects and specify the level of access
granted to those users.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/objectops/#set-object-acl) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: The changes to make to this Object's access controls.
content:
application/json:
schema:
required:
- acl
- name
properties:
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
- custom
description: >
The Access Control Level of the bucket, as a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
example: public-read
name:
type: string
description: >
The `name` of the object for which to update its Access Control List (ACL).
Use the [Object Storage Bucket Contents List](/docs/api/object-storage/#object-storage-bucket-contents-list)
endpoint to access all object names in a bucket.
responses:
'200':
description: The Object's canned ACL and policy.
content:
application/json:
schema:
type: object
properties:
acl:
type: string
enum:
- private
- public-read
- authenticated-read
- public-read-write
- custom
description: >
The Access Control Level of the bucket, as a canned ACL string.
For more fine-grained control of ACLs, use the S3 API directly.
example: public-read
acl_xml:
type: string
description: >
The full XML of the object's ACL policy.
example: "<AccessControlPolicy>...</AccessControlPolicy>"
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"acl": "public-read",
"name": "example.txt"
}' \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-acl
/object-storage/buckets/{clusterId}/{bucket}/object-list:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
get:
operationId: getObjectStorageBucketContent
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Bucket Contents List
description: |
Returns the contents of a bucket. The contents are paginated using a `marker`,
which is the name of the last object on the previous page. Objects may
be filtered by `prefix` and `delimiter` as well; see Query Parameters for more
information.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/objectops/#get-object) directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
parameters:
- name: marker
in: query
required: false
description: >
The "marker" for this request, which can be used to paginate through large buckets.
Its value should be the value of the `next_marker` property returned with the last page.
Listing bucket contents *does not* support arbitrary page access. See the `next_marker`
property in the responses section for more details.
schema:
type: string
- name: delimiter
in: query
required: false
description: >
The delimiter for object names; if given, object names will be returned
up to the first occurrence of this character. This is most commonly used
with the `/` character to allow bucket transversal in a manner similar to
a filesystem, however any delimiter may be used. Use in conjunction with
`prefix` to see object names past the first occurrence of the delimiter.
schema:
type: string
- name: prefix
in: query
required: false
description: >
Filters objects returned to only those whose name start with the given
prefix. Commonly used in conjunction with `delimiter` to allow transversal
of bucket contents in a manner similar to a filesystem.
schema:
type: string
- $ref: '#/components/parameters/pageSize'
responses:
'200':
description: One page of the requested bucket's contents.
content:
application/json:
schema:
properties:
data:
type: array
description: This page of objects in the bucket.
items:
$ref: '#/components/schemas/ObjectStorageObject'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-list
/object-storage/buckets/{clusterId}/{bucket}/object-url:
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
post:
operationId: createObjectStorageObjectURL
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Object URL Create
description: |
Creates a pre-signed URL to access a single Object in a bucket. This
can be used to share objects, and also to create/delete objects by using
the appropriate HTTP method in your request body's `method` parameter.
This endpoint is available for convenience. It is recommended that instead you
use the more [fully-featured S3 API](https://docs.ceph.com/en/latest/radosgw/s3/)
directly.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: Information about the request to sign.
content:
application/json:
schema:
required:
- name
- method
properties:
method:
type: string
description: The HTTP method allowed to be used with the pre-signed URL.
example: GET
default: GET
name:
type: string
description: >
The name of the object that will be accessed with the pre-signed URL. This object need not
exist, and no error will be returned if it doesn't. This behavior is
useful for generating pre-signed URLs to upload new objects to by
setting the `method` to "PUT".
example: example
content_type:
type: string
description: >
The expected `Content-type` header of the request this signed
URL will be valid for. If provided, the `Content-type` header
_must_ be sent with the request when this URL is used, and
_must_ be the same as it was when the signed URL was created.
Required for all methods *except* "GET" or "DELETE".
example: null
expires_in:
type: integer
minimum: 360
maximum: 86400
default: 3600
description: >
How long this signed URL will be valid for, in seconds. If
omitted, the URL will be valid for 3600 seconds (1 hour).
example: null
responses:
'200':
description: The URL with which to access your object.
content:
application/json:
schema:
properties:
url:
type: string
description: The signed URL to perform the request at.
example: https://us-east-1.linodeobjects.com/example-bucket/example?Signature=qr98TEucCntPgEG%2BsZQGDsJg93c%3D&Expires=1567609905&AWSAccessKeyId=G4YAF81XWY61DQM94SE0
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"method": "GET",
"name": "example"
}' \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-url
/object-storage/clusters:
x-linode-cli-command: object-storage
get:
operationId: getObjectStorageClusters
x-linode-cli-action: clusters-list
servers:
- url: https://api.linode.com/v4
summary: Clusters List
description: |
Returns a paginated list of Object Storage Clusters that are available for
use. Users can connect to the clusters with third party clients to create buckets
and upload objects.
tags:
- Object Storage
responses:
'200':
description: A paginated list of available clusters.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObjectStorageCluster'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/clusters
- lang: CLI
source: >
linode-cli object-storage clusters-list
/object-storage/clusters/{clusterId}:
x-linode-cli-command: object-storage
parameters:
- name: clusterId
in: path
description: The ID of the Cluster.
required: true
schema:
type: string
get:
operationId: getObjectStorageCluster
x-linode-cli-action: clusters-view
servers:
- url: https://api.linode.com/v4
summary: Cluster View
description: |
Returns a single Object Storage Cluster.
tags:
- Object Storage
responses:
'200':
description: The requested Cluster
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageCluster'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/clusters/us-east-1
- lang: CLI
source: >
linode-cli object-storage clusters-view us-east-1
/object-storage/keys:
x-linode-cli-command: object-storage
get:
operationId: getObjectStorageKeys
x-linode-cli-action: keys-list
servers:
- url: https://api.linode.com/v4
tags:
- Object Storage
summary: Object Storage Keys List
description: |
Returns a paginated list of Object Storage Keys for authenticating to
the Object Storage S3 API.
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: A paginated list of Object Storage Keys
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObjectStorageKey'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/keys
- lang: CLI
source: >
linode-cli object-storage keys-list
post:
operationId: createObjectStorageKeys
x-linode-cli-action: keys-create
servers:
- url: https://api.linode.com/v4
summary: Object Storage Key Create
description: |
Provisions a new Object Storage Key on your account.
* To create a Limited Access Key with specific permissions, send a `bucket_access`
array.
* To create a Limited Access Key without access to any buckets, send an empty
`bucket_access` array.
* To create an Access Key with unlimited access to all clusters and all buckets,
omit the `bucket_access` array.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: >
The label of the key to create. This is used to identify the created key.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageKey'
responses:
'200':
description: The new keypair. **This is the only time** the secret key is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "my-object-storage-key",
"bucket_access": [
{
"cluster": "ap-south-1",
"bucket_name": "bucket-example-1",
"permissions": "read_write"
},
{
"cluster": "us-east-1",
"bucket_name": "bucket-example-2",
"permissions": "read_only"
}
]
}' \
https://api.linode.com/v4/object-storage/keys
- lang: CLI
source: >
linode-cli object-storage keys-create \
--label "my-object-storage-key" \
--bucket_access '[{"cluster": "ap-south-1", "bucket_name": "bucket-example-1", "permissions": "read_write" }]'
/object-storage/keys/{keyId}:
x-linode-cli-command: object-storage
parameters:
- name: keyId
in: path
description: The key to look up.
required: true
schema:
type: integer
get:
operationId: getObjectStorageKey
x-linode-cli-action: keys-view
servers:
- url: https://api.linode.com/v4
summary: Object Storage Key View
description: |
Returns a single Object Storage Key provisioned for your account.
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
tags:
- Object Storage
responses:
'200':
description: The keypair
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/keys/12345
- lang: CLI
source: >
linode-cli object-storage keys-view \
--keyId 12345
put:
operationId: updateObjectStorageKey
x-linode-cli-action: keys-update
servers:
- url: https://api.linode.com/v4
summary: Object Storage Key Update
description: |
Updates an Object Storage Key on your account.
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
tags:
- Object Storage
requestBody:
description: The fields to update.
content:
application/json:
schema:
type: object
properties:
label:
type: string
description: The label for this keypair, for display purposes only.
example: my-key
responses:
'200':
description: Update Successful
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "my-object-storage-key"
}' \
https://api.linode.com/v4/object-storage/keys/12345
- lang: CLI
source: >
linode-cli object-storage keys-update \
--keyId 12345
--label "my-object-storage-key"
delete:
operationId: deleteObjectStorageKey
x-linode-cli-action: keys-delete
servers:
- url: https://api.linode.com/v4
summary: Object Storage Key Revoke
description: |
Revokes an Object Storage Key. This keypair will no longer be usable by third-party clients.
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
tags:
- Object Storage
responses:
'200':
description: Deletion successful
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/object-storage/keys/12345
- lang: CLI
source: >
linode-cli object-storage keys-delete 12345
/object-storage/cancel:
x-linode-cli-command: object-storage
post:
operationId: cancelObjectStorage
x-linode-cli-action: cancel
servers:
- url: https://api.linode.com/v4
summary: Object Storage Cancel
description: |
Cancel Object Storage on an Account.
**Warning**: Removes all buckets and their contents from your Account. This data is irretrievable once removed.
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
tags:
- Object Storage
responses:
'200':
description: Object Storage cancellation successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/object-storage/cancel
- lang: CLI
source: >
linode-cli object-storage cancel
/object-storage/buckets/{clusterId}/{bucket}/ssl:
x-linode-cli-command: object-storage
parameters:
- name: clusterId
in: path
description: The ID of the cluster this bucket exists in.
required: true
schema:
type: string
- name: bucket
in: path
description: The bucket name.
required: true
schema:
type: string
get:
operationId: getObjectStorageSSL
x-linode-cli-action: ssl-view
servers:
- url: https://api.linode.com/v4
summary: Object Storage TLS/SSL Cert View
description: |
Returns a boolean value indicating if this bucket has a corresponding TLS/SSL certificate that was
uploaded by an Account user.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: >
Returns a boolean value indicating if this bucket has a corresponding TLS/SSL certificate that was
uploaded by an Account user.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageSSLResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/ssl
- lang: CLI
source: >
linode-cli object-storage ssl-view \
us-east-1 example-bucket
post:
operationId: createObjectStorageSSL
x-linode-cli-action: ssl-upload
servers:
- url: https://api.linode.com/v4
summary: Object Storage TLS/SSL Cert Upload
description: |
Upload a TLS/SSL certificate and private key to be served when you visit your Object Storage bucket via HTTPS.
Your TLS/SSL certificate and private key are stored encrypted at rest.
To replace an expired certificate, [delete your current certificate](/docs/api/object-storage/#object-storage-tlsssl-cert-delete)
and upload a new one.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
requestBody:
description: Upload this TLS/SSL certificate with its corresponding secret key.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageSSL'
responses:
'200':
description: Returns whether this bucket has a corresponding TLS/SSL certificate that was uploaded by a user.
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectStorageSSLResponse'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"certificate": "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----",
"private_key": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----"
}' \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/ssl
- lang: CLI
source: >
linode-cli object-storage ssl-upload \
us-east-1 example-bucket \
--certificate "-----BEGIN CERTIFICATE-----
CERTIFICATE_INFORMATION
-----END CERTIFICATE-----" \
--private_key "-----BEGIN PRIVATE KEY-----
PRIVATE_KEY_INFORMATION
-----END PRIVATE KEY-----"
delete:
operationId: deleteObjectStorageSSL
x-linode-cli-action: ssl-delete
servers:
- url: https://api.linode.com/v4
summary: Object Storage TLS/SSL Cert Delete
description: |
Deletes this Object Storage bucket's user uploaded TLS/SSL certificate and private key.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_write
responses:
'200':
description: Deletes this Object Storage bucket's user uploaded TLS/SSL certificate and private key.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/ssl
- lang: CLI
source: >
linode-cli object-storage ssl-delete \
us-east-1 example-bucket
/object-storage/transfer:
get:
operationId: getObjectStorageTransfer
x-linode-cli-skip: true
servers:
- url: https://api.linode.com/v4
summary: Object Storage Transfer View
description: |
The amount of outbound data transfer used by your account's Object Storage buckets.
Object Storage adds 1 terabyte of outbound data transfer to your data transfer pool.
See the [Object Storage Pricing and Limitations](/docs/guides/pricing-and-limitations/)
guide for details on Object Storage transfer quotas.
tags:
- Object Storage
security:
- personalAccessToken: []
- oauth:
- object_storage:read_only
responses:
'200':
description: >
Returns the amount of outbound data transfer used by your account's Object Storage buckets.
content:
application/json:
schema:
properties:
used:
type: integer
description: >
The amount of outbound data transfer used by your account's Object Storage buckets,
in bytes, for the current month's billing cycle.
example: 12956600198
readOnly: true
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/object-storage/transfer/
/profile:
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Profile View
description: >
Returns information about the current User. This can be used to see
who is acting in applications where more than one token is managed. For
example, in third-party OAuth applications.
This endpoint is always accessible, no matter what OAuth scopes the acting token has.
operationId: getProfile
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth: []
responses:
'200':
description: Profile response.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile
- lang: CLI
source: >
linode-cli profile view
put:
tags:
- Profile
summary: Profile Update
description: >
Update information in your Profile. This endpoint requires the
"account:read_write" OAuth Scope.
operationId: updateProfile
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
responses:
'200':
description: Profile updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Profile'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"email": "example-user@gmail.com",
"timezone": "US/Eastern",
"email_notifications": true,
"lish_auth_method": "keys_only",
"authorized_keys": null,
"two_factor_auth": true,
"restricted": false
}' \
https://api.linode.com/v4/profile
- lang: CLI
source: >
linode-cli profile update \
--email example-user@gmail.com \
--timezone US/Eastern \
--email_notifications true \
--list_auth_method keys_only \
--two_factor_auth true \
--restricted false
/profile/apps:
x-linode-cli-command: profile
get:
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Profile
summary: Authorized Apps List
description: >
This is a collection of OAuth apps that you've given access to your Account, and
includes the level of access granted.
operationId: getProfileApps
x-linode-cli-action: apps-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: |
A paginated list of apps you've authorized.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AuthorizedApp'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/apps
- lang: CLI
source: >
linode-cli profile apps-list
/profile/apps/{appId}:
parameters:
- name: appId
in: path
required: true
description: The authorized app ID to manage.
schema:
type: integer
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Authorized App View
description: >
Returns information about a single app you've authorized to access your
Account.
operationId: getProfileApp
x-linode-cli-action: app-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The app requested.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthorizedApp'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/apps/123
- lang: CLI
source: >
linode-cli profile app-view 1234
delete:
tags:
- Profile
summary: App Access Revoke
description: >
Expires this app token. This token may no longer be used to
access your Account.
operationId: deleteProfileApp
x-linode-cli-action: app-delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: App's authorization has been revoked.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/profile/apps/123
- lang: CLI
source: >
linode-cli profile app-delete 123
/profile/grants:
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Grants List
description: >
This returns a GrantsResponse describing what the acting User has been
granted access to. For unrestricted users, this will return a 204 and
no body because unrestricted users have access to everything without
grants. This will not return information about entities you do not have
access to. This endpoint is useful when writing third-party OAuth
applications to see what options you should present to the acting User.
For example, if they do not have `global.add_linodes`, you might not
display a button to deploy a new Linode.
Any client may access this endpoint; no OAuth scopes are required.
operationId: getProfileGrants
x-linode-cli-action: grants
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth: []
responses:
'200':
description: GrantsResponse
content:
application/json:
schema:
$ref: '#/components/schemas/GrantsResponse'
'204':
description: >
This is an unrestricted User, who has no grants. This User can access
everything on the Account.
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/grants
/profile/tfa-disable:
x-linode-cli-command: profile
post:
tags:
- Profile
summary: Two Factor Authentication Disable
description: >
Disables Two Factor Authentication for your User. Once successful,
login attempts from untrusted computers will only require a password
before being successful. This is less secure, and is discouraged.
operationId: tfaDisable
x-linode-cli-action: tfa-disable
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: TFA disabled.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/profile/tfa-disable
- lang: CLI
source: >
linode-cli profile tfa-disable
/profile/tfa-enable:
x-linode-cli-command: profile
post:
tags:
- Profile
summary: Two Factor Secret Create
description: |
Generates a Two Factor secret for your User. To enable TFA for your User, enter the secret obtained from this command with the **Two Factor Authentication Confirm/Enable** ([POST /profile/tfa-enable-confirm](/docs/api/profile/#two-factor-authentication-confirmenable)) command.
Once enabled, logins from untrusted computers are required to provide
a TFA code before they are successful.
**Note**: Before you can enable TFA, security questions must be answered for your User by accessing the **Security Questions Answer** ([POST /profile/security-questions](/docs/api/profile/#security-questions-answer)) command.
operationId: tfaEnable
x-linode-cli-action: tfa-enable
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Two Factor secret generated
content:
application/json:
schema:
properties:
secret:
type: string
description: >
Your Two Factor secret. This is used to generate
time-based two factor codes required for logging in. Doing
this will be required to confirm TFA an actually enable it.
example: 5FXX6KLACOC33GTC
expiry:
type: string
format: date-time
description: >
When this Two Factor secret expires.
example: 2018-03-01T00:01:01
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/profile/tfa-enable
- lang: CLI
source: >
linode-cli profile tfa-enable
/profile/tfa-enable-confirm:
x-linode-cli-command: profile
post:
tags:
- Profile
summary: Two Factor Authentication Confirm/Enable
description: >
Confirms that you can successfully generate Two Factor codes and
enables TFA on your Account. Once this is complete, login attempts
from untrusted computers will be required to provide a Two Factor code
before they are successful.
operationId: tfaConfirm
x-linode-cli-action: tfa-confirm
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The Two Factor code you generated with your Two Factor secret.
required: true
content:
application/json:
schema:
properties:
tfa_code:
type: string
description: >
The Two Factor code you generated with your Two Factor secret.
These codes are time-based, so be sure it is current.
example: "213456"
responses:
'200':
description: TFA enabled successfully
content:
application/json:
schema:
properties:
scratch:
type: string
description: >
A one-use code that can be used in place of your Two Factor
code, in case you are unable to generate one. Keep this in
a safe place to avoid being locked out of your Account.
example: sample two factor scratch
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"tfa_code": "213456"
}' \
https://api.linode.com/v4/profile/tfa-enable-confirm
- lang: CLI
source: >
linode-cli profile tfa-confirm \
--tfa_code 213456
/profile/tokens:
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Personal Access Tokens List
description: >
Returns a paginated list of Personal Access Tokens currently active for
your User.
operationId: getPersonalAccessTokens
x-linode-cli-action: tokens-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of active tokens.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PersonalAccessToken'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/tokens
- lang: CLI
source: >
linode-cli profile tokens-list
post:
tags:
- Profile
summary: Personal Access Token Create
description: >
Creates a Personal Access Token for your User. The raw token will
be returned in the response, but will never be returned again afterward
so be sure to take note of it. You may create a token with _at most_
the scopes of your current token. The created token will be able to
access your Account until the given expiry, or until it is revoked.
operationId: createPersonalAccessToken
x-linode-cli-action: token-create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Information about the requested token.
required: true
content:
application/json:
schema:
properties:
scopes:
type: string
format: oauth-scope
description: >
The scopes to create the token with. These cannot be changed
after creation, and may not exceed the scopes of the acting token.
If omitted, the new token will have the same scopes as the acting
token.
example: '*'
expiry:
type: string
format: date-time
description: >
When this token should be valid until. If omitted, the new token
will be valid until it is manually revoked.
example: null
label:
$ref: '#/components/schemas/PersonalAccessToken/properties/label'
responses:
'200':
description: Token created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessToken'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"scopes": "*",
"expiry": "2018-01-01T13:46:32",
"label": "linode-cli"
}' \
https://api.linode.com/v4/profile/tokens
- lang: CLI
source: >
linode-cli profile token-create \
--scopes '*' \
--expiry '2018-01-01T13:46:32' \
--label linode-cli
/profile/tokens/{tokenId}:
parameters:
- name: tokenId
in: path
description: The ID of the token to access.
required: true
schema:
type: integer
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Personal Access Token View
description: >
Returns a single Personal Access Token.
operationId: getPersonalAccessToken
x-linode-cli-action: token-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested token.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessToken'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/tokens/123
- lang: CLI
source: >
linode-cli profile token-view 123
put:
tags:
- Profile
summary: Personal Access Token Update
description: >
Updates a Personal Access Token.
operationId: updatePersonalAccessToken
x-linode-cli-action: token-update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessToken'
responses:
'200':
description: Token updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalAccessToken'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "linode-cli"
}' \
https://api.linode.com/v4/profile/tokens/123
- lang: CLI
source: >
linode-cli profile token-update 123 \
--label linode-cli
delete:
tags:
- Profile
summary: Personal Access Token Revoke
description: >
Revokes a Personal Access Token. The token will be invalidated
immediately, and requests using that token will fail with a 401. It is
possible to revoke access to the token making the request to revoke a token,
but keep in mind that doing so could lose you access to the api and require
you to create a new token through some other means.
operationId: deletePersonalAccessToken
x-linode-cli-action: token-delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Token revoked successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/profile/tokens/123
- lang: CLI
source: >
linode-cli profile token-delete 123
/profile/logins:
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Logins List
description: >
Returns a collection of successful account logins from this user during the last
90 days.
operationId: getProfileLogins
x-linode-cli-action: logins-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
An array of successful account logins from this user during
the last 90 days.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Login'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/logins
- lang: CLI
source: >
linode-cli profile logins-list
/profile/logins/{loginId}:
parameters:
- name: loginId
in: path
description: The ID of the login object to access.
required: true
schema:
type: integer
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Login View
description: >
Returns a login object displaying information about a successful
account login from this user.
operationId: getProfileLogin
x-linode-cli-action: login-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested login object.
content:
application/json:
schema:
$ref: '#/components/schemas/Login'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/logins/1234
- lang: CLI
source: >
linode-cli profile login-view 1234
/profile/devices:
x-linode-cli-command: profile
get:
tags:
- Profile
summary: Trusted Devices List
description: >
Returns a paginated list of active TrustedDevices for your User.
Browsers with an active Remember Me Session are logged into your account
until the session expires or is revoked.
operationId: getDevices
x-linode-cli-action: devices-list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of TrustedDevice objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TrustedDevice'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/devices
- lang: CLI
source: >
linode-cli profile devices-list
/profile/devices/{deviceId}:
x-linode-cli-command: profile
parameters:
- name: deviceId
in: path
description: The ID of the TrustedDevice
required: true
schema:
type: integer
get:
tags:
- Profile
summary: Trusted Device View
description: >
Returns a single active TrustedDevice for your User.
operationId: getTrustedDevice
x-linode-cli-action: device-view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: The requested TrustedDevice object
content:
application/json:
schema:
$ref: '#/components/schemas/TrustedDevice'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/devices/123
- lang: CLI
source: >
linode-cli profile device-view 123
delete:
tags:
- Profile
summary: Trusted Device Revoke
description: >
Revoke an active TrustedDevice for your User. Once a TrustedDevice is revoked, this
device will have to log in again before accessing your Linode account.
operationId: revokeTrustedDevice
x-linode-cli-action: device-revoke
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Session revoked successfully
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/profile/devices/123
- lang: CLI
source: >
linode-cli profile device-revoke 123
/profile/security-questions:
x-linode-cli-command: security-questions
get:
x-linode-grant: read_only
servers:
- url: https://api.linode.com/v4
tags:
- Profile
summary: Security Questions List
description: >
Returns a collection of security questions and their responses, if any, for your User Profile.
operationId: getSecurityQuestions
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a list of security questions.
content:
application/json:
x-linode-cli-nested-list: security_questions
x-linode-cli-use-schema:
type: object
properties:
security_questions.id:
x-linode-cli-display: 1
security_questions.question:
x-linode-cli-display: 2
security_questions.response:
x-linode-cli-display: 3
schema:
$ref: '#/components/schemas/SecurityQuestionsGet'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/security-questions
- lang: CLI
source: >
linode-cli security-questions list
post:
tags:
- Profile
summary: Security Questions Answer
description: |
Adds security question responses for your User.
Requires exactly three unique questions.
Previous responses are overwritten if answered or reset to `null` if unanswered.
**Note**: Security questions must be answered for your User prior to accessing the **Two Factor Secret Create** ([POST /profile/tfa-enable](/docs/api/profile/#two-factor-secret-create)) command.
operationId: postSecurityQuestions
x-linode-cli-action: answer
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Answer Security Questions
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityQuestionsPost'
responses:
'200':
description: Security Questions answered successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityQuestionsPost'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"security_questions": [
{
"question_id": 1,
"response": "secret answer 1"
},
{
"question_id": 2,
"response": "secret answer 2"
},
{
"question_id": 11,
"response": "secret answer 3"
}
]
}' \
https://api.linode.com/v4/profile/security-questions
/profile/sshkeys:
x-linode-cli-command: sshkeys
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Profile
summary: SSH Keys List
description: >
Returns a collection of SSH Keys you've added to your Profile.
operationId: getSSHKeys
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of SSH Key objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SSHKey'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/sshkeys
- lang: CLI
source: >
linode-cli sshkeys list
post:
tags:
- Profile
summary: SSH Key Add
description: >
Adds an SSH Key to your Account profile.
operationId: addSSHKey
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Add SSH Key
content:
application/json:
schema:
$ref: '#/components/schemas/SSHKeyRequest'
responses:
'200':
description: SSH Key associated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SSHKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "My SSH Key"
"ssh_key": "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
}' \
https://api.linode.com/v4/profile/sshkeys
- lang: CLI
source: >
linode-cli sshkeys create \
--label "My SSH Key"
--ssh_key "ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer"
/profile/sshkeys/{sshKeyId}:
x-linode-cli-command: sshkeys
parameters:
- name: sshKeyId
in: path
description: The ID of the SSHKey
required: true
schema:
type: integer
get:
tags:
- Profile
summary: SSH Key View
description: >
Returns a single SSH Key object identified by `id` that you have access
to view.
operationId: getSSHKey
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: An SSH Key object
content:
application/json:
schema:
$ref: '#/components/schemas/SSHKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/profile/sshkeys/42
- lang: CLI
source: >
linode-cli sshkeys view 42
put:
tags:
- Profile
summary: SSH Key Update
description: >
Updates an SSH Key that you have permission to `read_write`.
operationId: updateSSHKey
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The fields to update.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SSHKey'
responses:
'200':
description: SSH Key updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SSHKey'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "my laptop"
}' \
https://api.linode.com/v4/profile/sshkey/42
- lang: CLI
source: >
linode-cli sshkey update 42 \
--label "my laptop"
delete:
tags:
- Profile
summary: SSH Key Delete
description: >
Deletes an SSH Key you have access to.
**Note:** deleting an SSH Key will *not* remove it from any Linode or
Disk that was deployed with `authorized_keys`. In those cases, the keys
must be manually deleted on the Linode or Disk.
This endpoint will only delete the key's association from your Profile.
operationId: deleteSSHKey
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: SSH Key deleted successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authoriztion: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/profile/sshkeys/42
- lang: CLI
source: >
linode-cli sshkey delete 42
/profile/phone-number:
x-linode-cli-command: phone
delete:
x-linode-grant: read_write
tags:
- Profile
summary: Phone Number Delete
description: |
Delete the verified phone number for the User making this request.
Use this command to opt out of SMS messages for the requesting User after a phone number has been verified with the **Phone Number Verify** ([POST /profile/phone-number/verify](/docs/api/profile/#phone-number-verify)) command.
operationId: deleteProfilePhoneNumber
x-linode-cli-command: delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: >
Phone number deletion request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/profile/phone-number
- lang: CLI
source: >
linode-cli phone delete
post:
x-linode-grant: read_write
tags:
- Profile
summary: Phone Number Verification Code Send
description: |
Send a one-time verification code via SMS message to the submitted phone number. Providing your phone number helps ensure you can securely access your Account in case other ways to connect are lost. Your phone number is only used to verify your identity by sending an SMS message. Standard carrier messaging fees may apply.
* By accessing this command you are opting in to receive SMS messages. You can opt out of SMS messages by using the **Phone Number Delete** ([DELETE /profile/phone-number](/docs/api/profile/#phone-number-delete)) command after your phone number is verified.
* Verification codes are valid for 10 minutes after they are sent.
* Subsequent requests made prior to code expiration result in sending the same code.
Once a verification code is received, verify your phone number with the **Phone Number Verify** ([POST /profile/phone-number/verify](/docs/api/profile/#phone-number-verify)) command.
operationId: postProfilePhoneNumber
x-linode-cli-command: sms-code-send
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Enter a phone number and country code for verification.
content:
application/json:
schema:
required:
- iso_code
- phone_number
type: object
properties:
iso_code:
type: string
description: The two-letter ISO 3166 country code associated with the phone number.
example: US
phone_number:
type: string
description: A valid phone number.
format: phone
example: 555-555-5555
responses:
'200':
description: >
Phone number verification code request successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"iso_code": "US",
"phone_number": "555-555-5555"
}' \
https://api.linode.com/v4/profile/phone-number
- lang: CLI
source: >
linode-cli phone sms-code-send \
--iso-code US \
--phone-number 555-555-5555
/profile/phone-number/verify:
x-linode-cli-command: phone
post:
x-linode-grant: read_write
tags:
- Profile
summary: Phone Number Verify
description: |
Verify a phone number by confirming the one-time code received via SMS message after accessing the **Phone Verification Code Send** ([POST /profile/phone-number](/docs/api/profile/#phone-number-verification-code-send)) command.
* Verification codes are valid for 10 minutes after they are sent.
* Only the same User that made the verification code request can use that code with this command.
Once completed, the verified phone number is assigned to the User making the request. To change the verified phone number for a User, first use the **Phone Number Delete** ([DELETE /profile/phone-number](/docs/api/profile/#phone-number-delete)) command, then begin the verification process again with the **Phone Verification Code Send** ([POST /profile/phone-number](/docs/api/profile/#phone-number-verification-code-send)) command.
operationId: postProfilePhoneNumberVerify
x-linode-cli-command: verify
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Enter a phone verification code for confirmation.
content:
application/json:
schema:
required:
- otp_code
type: object
properties:
otp_code:
type: string
description: The one-time code received via SMS message after accessing the **Phone Verification Code Send** ([POST /profile/phone-number](/docs/api/profile/#phone-number-verification-code-send)) command.
example: "US"
responses:
'200':
description: >
Phone number verification successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"otp_code": "123456"
}' \
https://api.linode.com/v4/profile/phone-number/verify
- lang: CLI
source: >
linode-cli phone verify \
--otp_code 123456
/profile/preferences:
x-linode-cli-command: profile
get:
x-linode-grant: read_only
tags:
- Profile
summary: User Preferences View
description: |
View a list of user preferences tied to the OAuth client that generated
the token making the request. The user preferences endpoints allow
consumers of the API to store arbitrary JSON data, such as a user's font
size preference or preferred display name. User preferences are available
for each OAuth client registered to your account, and as such an account can
have multiple user preferences.
operationId: getUserPreferences
x-linode-cli-action: preferences-view
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns an object of user preferences.
content:
application/json:
schema:
type: object
description: A dictionary of user preferences.
example: { "key1": "value1", "key2": "value2"}
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X GET \
https://api.linode.com/v4/profile/preferences
put:
tags:
- Profile
summary: User Preferences Update
description: >
Updates a user's preferences. These preferences are tied to the
OAuth client that generated the token making the request. The user
preferences endpoints allow consumers of the API to store arbitrary
JSON data, such as a user's font size preference or preferred display
name. An account may have multiple preferences. Preferences, and the
pertaining request body, may contain any arbitrary JSON data that
the user would like to store.
operationId: updateUserPreferences
x-linode-cli-action: preferences-update
x-linode-cli-skip: true
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The user preferences to update or store.
required: true
content:
application/json:
schema:
type: object
description: |
Arbitrary JSON of your choosing.
responses:
'200':
description: Returns an object of user preferences.
content:
application/json:
schema:
type: object
description: An object of user preferences.
example: { "key1": "value1", "key2": "value2"}
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"key1": "value1",
"key1": "value2"
}' \
https://api.linode.com/v4/profile/preferences
/regions:
x-linode-cli-command: regions
get:
tags:
- Regions
summary: Regions List
description: |
Lists the Regions available for Linode services. Not all services are guaranteed to be
available in all Regions.
x-linode-redoc-load-ids: true
operationId: getRegions
x-linode-cli-action: list
responses:
'200':
description: Returns an array of Regions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Region'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/regions
- lang: CLI
source: >
linode-cli regions list
/regions/{regionId}:
x-linode-cli-command: regions
parameters:
- name: regionId
in: path
description: ID of the Region to look up.
required: true
schema:
type: string
get:
tags:
- Regions
summary: Region View
description: >
Returns a single Region.
operationId: getRegion
x-linode-cli-action: view
responses:
'200':
description: A single Region object.
content:
application/json:
schema:
$ref: '#/components/schemas/Region'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl https://api.linode.com/v4/regions/us-east
- lang: CLI
source: >
linode-cli regions view us-east
/support/tickets:
x-linode-cli-command: tickets
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Support
summary: Support Tickets List
description: >
Returns a collection of Support Tickets on your
Account. Support Tickets can be both tickets you open with Linode
for support, as well as tickets generated by Linode regarding
your Account.
This collection includes all Support Tickets generated on your Account,
with open tickets returned first.
operationId: getTickets
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of SupportTicket objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SupportTicket'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/support/tickets
- lang: CLI
source: >
linode-cli tickets list
post:
x-linode-grant: read_write
tags:
- Support
summary: Support Ticket Open
description: >
Open a Support Ticket.
Only one of the ID attributes (`linode_id`, `domain_id`, etc.) can be set
on a single Support Ticket.
operationId: createTicket
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Open a Support Ticket.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicketRequest'
responses:
'200':
description: Support Ticket opened.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicket'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"description": "I'm having trouble setting the root password on my Linode. I tried following the instructions but something is not working and I'm not sure what I'm doing wrong. Can you please help me figure out how I can reset it?",
"linode_id": 123,
"summary": "Having trouble resetting root password on my Linode"
}' \
https://api.linode.com/v4/support/tickets
- lang: CLI
source: >
linode-cli tickets create \
--description "I'm having trouble setting the root password on my Linode. I tried following the instructions but something is not working and I'm not sure what I'm doing wrong. Can you please help me figure out how I can reset it?" \
--linode_id 123 \
--summary "Having trouble resetting root password on my Linode"
/support/tickets/{ticketId}:
parameters:
- name: ticketId
in: path
description: The ID of the Support Ticket.
required: true
schema:
type: integer
x-linode-cli-command: tickets
get:
x-linode-grant: read_only
tags:
- Support
summary: Support Ticket View
description: >
Returns a Support Ticket under your Account.
operationId: getTicket
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a single SupportTicket object.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicket'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/support/tickets/11223344
- lang: CLI
source: >
linode-cli tickets view 11223344
/support/tickets/{ticketId}/attachments:
parameters:
- name: ticketId
in: path
description: The ID of the Support Ticket.
required: true
schema:
type: integer
x-linode-cli-command: tickets
post:
x-linode-grant: read_write
tags:
- Support
summary: Ticket Attachment Create
description: >
Adds a file attachment to an existing Support
Ticket on your Account. File attachments are used to assist our
Support team in resolving your Ticket. Examples of attachments
are screen shots and text files that provide additional information.
Note: Accepted file extensions include: .gif, .jpg, .jpeg, .pjpg,
.pjpeg, .tif, .tiff, .png, .pdf, or .txt.
operationId: createTicketAttachment
x-linode-cli-skip: true
x-linode-cli-action: upload-attachment
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Add an attachment.
required: true
content:
multipart/form-data:
schema:
required:
- file
properties:
file:
type: string
description: >
The local, absolute path to the file you want to attach to
your Support Ticket.
example: '/Users/LinodeGuy/pictures/screen_shot.jpg'
responses:
'200':
description: Attachment created.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
-F 'file=@/Users/LinodeGuy/pictures/screen_shot.jpg' \
https://api.linode.com/v4/support/tickets/11223344/attachments
/support/tickets/{ticketId}/close:
parameters:
- name: ticketId
in: path
description: The ID of the Support Ticket.
required: true
schema:
type: integer
x-linode-cli-command: tickets
post:
x-linode-grant: read_write
tags:
- Support
summary: Support Ticket Close
description: >
Closes a Support Ticket you have access to modify.
operationId: closeTicket
x-linode-cli-action: close
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Support Ticket closed successfully.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/support/tickets/11223344/close
- lang: CLI
source: >
linode-cli tickets close 11223344
/support/tickets/{ticketId}/replies:
parameters:
- name: ticketId
in: path
description: The ID of the Support Ticket.
required: true
schema:
type: integer
x-linode-cli-command: tickets
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Support
summary: Replies List
description: >
Returns a collection of replies to a Support Ticket on
your Account.
operationId: getTicketReplies
x-linode-cli-action: replies
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: Returns a paginated list of SupportTicketReply objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SupportTicketReply'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/support/tickets/11223344/replies
- lang: CLI
source: >
linode-cli tickets replies 11223344
post:
x-linode-grant: read_write
tags:
- Support
summary: Reply Create
description: >
Adds a reply to an existing Support Ticket.
operationId: createTicketReply
x-linode-cli-action: reply
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: Add a reply.
required: true
content:
application/json:
schema:
required:
- description
properties:
description:
type: string
description: >
The content of your reply.
minLength: 1
maxLength: 65535
example: >
Thank you for your help. I was able to figure out what the
problem was and I successfully reset my password. You guys are
the best!
responses:
'200':
description: Reply created.
content:
application/json:
schema:
$ref: '#/components/schemas/SupportTicketReply'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"description": "Thank you for your help. I was able to figure out what the problem was and I successfully reset my password. You guys are the best!"
}' \
https://api.linode.com/v4/support/tickets/11223344/replies
- lang: CLI
source: >
linode-cli tickets reply 11223344 \
--description "Thank you for your help. I was able to figure out what the problem was and I successfully reset my password. You guys are the best!"
/tags:
x-linode-cli-command: tags
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Tags
summary: Tags List
description: >
Tags are User-defined labels attached to objects in your Account, such
as Linodes. They are used for specifying and grouping attributes of
objects that are relevant to the User.
This endpoint returns a paginated list of Tags on your account.
operationId: getTags
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: A paginated list of Tags
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Tag'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/tags
post:
tags:
- Tags
summary: New Tag Create
description: >
Creates a new Tag and optionally tags requested objects with it
immediately.
**Important**: You must be an unrestricted User in order to add or modify
Tags.
operationId: createTag
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- account:read_write
requestBody:
description: >
The tag to create, and optionally the objects to tag.
content:
application/json:
schema:
type: object
required:
- label
properties:
label:
type: string
description: >
The new Tag.
minLength: 3
maxLength: 50
example: example tag
linodes:
type: array
items:
type: integer
description: >
A list of Linode IDs to apply the new Tag to. You must be
allowed to `read_write` all of the requested Linodes, or the
Tag will not be created and an error will be returned.
example:
- 123
- 456
domains:
type: array
items:
type: integer
description: >
A list of Domain IDs to apply the new Tag to. You must be
allowed to `read_write` all of the requested Domains, or the
Tag will not be created and an error will be returned.
example:
- 564
- 565
volumes:
type: array
items:
type: integer
description: >
A list of Volume IDs to apply the new Tag to. You must be
allowed to `read_write` all of the requested Volumes, or the
Tag will not be created and an error will be returned.
example:
- 9082
- 10003
nodebalancers:
type: array
items:
type: integer
description: >
A list of NodeBalancer IDs to apply the new Tag to. You must
be allowed to `read_write` all of the requested NodeBalancers,
or the Tag will not be created and an error will be returned.
example:
- 10301
- 10501
responses:
'200':
description: The new Tag.
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "example tag",
"linodes": [123,456],
"volumes": [9082,10003]
}' \
https://api.linode.com/v4/tags
- lang: CLI
source: >
linode-cli tags create \
--label 'example tag' \
--linodes 123 \
--linodes 456 \
--volumes 9082 \
--volumes 10003
/tags/{label}:
x-linode-cli-command: tags
parameters:
- name: label
in: path
schema:
type: string
required: true
get:
summary: Tagged Objects List
description: >
Returns a paginated list of all objects you've tagged with the requested
Tag. This is a mixed collection of all object types.
tags:
- Tags
operationId: getTaggedObjects
x-linode-cli-command: view
x-linode-cli-skip: true
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
security:
- personalAccessToken: []
- oauth:
- account:read_only
responses:
'200':
description: >
A paginated list of objects, organized by type, that have been
tagged with the requested Tag.
content:
application/json:
schema:
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
example: 'linode'
data:
oneOf:
- x-linode-ref-name: "linode"
$ref: '#/components/schemas/Linode'
- x-linode-ref-name: "domain"
$ref: '#/components/schemas/Domain'
- x-linode-ref-name: "volume"
$ref: '#/components/schemas/Volume'
- x-linode-ref-name: "nodeBalancer"
$ref: '#/components/schemas/NodeBalancer'
discriminator:
propertyName: type
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
"https://api.linode.com/v4/tags/example tag"
delete:
summary: Tag Delete
description: >
Remove a Tag from all objects and delete it.
**Important**: You must be an unrestricted User in order to add or modify
Tags.
tags:
- Tags
operationId: deleteTag
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- account:read_write
responses:
'200':
description: Tag deleted.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
/volumes:
x-linode-cli-command: volumes
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
summary: Volumes List
description: >
Returns a paginated list of Volumes you have permission to view.
tags:
- Volumes
operationId: getVolumes
x-linode-cli-action: list
security:
- personalAccessToken: []
- oauth:
- volumes:read_only
responses:
'200':
description: Returns an array of all Volumes on your Account.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Volume'
page:
$ref: '#/components/schemas/PaginationEnvelope/properties/page'
pages:
$ref: '#/components/schemas/PaginationEnvelope/properties/pages'
results:
$ref: '#/components/schemas/PaginationEnvelope/properties/results'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/volumes
- lang: CLI
source: >
linode-cli volumes list
post:
x-linode-charge: true
x-linode-grant: add_volumes
summary: Volume Create
description: >
Creates a Volume on your Account. In order
for this to complete successfully, your User must have the `add_volumes`
grant. Creating a new Volume will start accruing additional charges
on your account.
tags:
- Volumes
operationId: createVolume
x-linode-cli-action: create
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
requestBody:
description: The requested initial state of a new Volume.
required: true
x-linode-cli-allowed-defaults:
- region
content:
application/json:
schema:
type: object
required:
- label
properties:
region:
type: string
description: >
The Region to deploy this Volume in. This is only required
if a linode_id is not given.
example: null
linode_id:
type: integer
description: >
The Linode this volume should be attached to upon creation.
If not given, the volume will be created without an attachment.
example: 123
size:
type: integer
description: >
The initial size of this volume, in GB. Be aware that volumes
may only be resized up after creation.
example: 20
default: 20
label:
type: string
description: >
The Volume's label, which is also used in the
`filesystem_path` of the resulting volume.
example: my-volume
minLength: 1
maxLength: 32
pattern: '^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$'
config_id:
type: integer
description: >
When creating a Volume attached to a Linode, the ID of the
Linode Config to include the new Volume in. This Config
must belong to the Linode referenced by `linode_id`. Must
_not_ be provided if `linode_id` is not sent. If a
`linode_id` is sent without a `config_id`, the volume will be
attached:
* to the Linode's only config if it only has one config.
* to the Linode's last used config, if possible.
If no config can be selected for attachment, an error will be
returned.
example: 23456
tags:
x-linode-filterable: true
description: >
An array of Tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
responses:
'200':
description: >
Creating Volume.
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "my-volume",
"size": 20,
"linode_id": 12346
}' \
https://api.linode.com/v4/volumes
- lang: CLI
source: >
linode-cli volumes create \
--label my-volume \
--size 20 \
--linode_id 12346 \
--no-defaults
/volumes/{volumeId}:
parameters:
- name: volumeId
in: path
description: ID of the Volume to look up.
required: true
schema:
type: integer
x-linode-cli-command: volumes
get:
x-linode-grant: read_only
parameters:
- $ref: '#/components/parameters/pageOffset'
- $ref: '#/components/parameters/pageSize'
tags:
- Volumes
summary: Volume View
description: >
Get information about a single Volume.
operationId: getVolume
x-linode-cli-action: view
security:
- personalAccessToken: []
- oauth:
- volumes:read_only
responses:
'200':
description: Returns a single Volume object.
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
links:
attach:
$ref: '#/components/links/attachVolume'
clone:
$ref: '#/components/links/cloneVolume'
detach:
$ref: '#/components/links/detachVolume'
resize:
$ref: '#/components/links/resizeVolume'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Authorization: Bearer $TOKEN" \
https://api.linode.com/v4/volumes/12345
- lang: CLI
source: >
linode-cli volumes view 12345
put:
x-linode-grant: read_write
tags:
- Volumes
summary: Volume Update
description: >
Updates a Volume that you have permission to `read_write`.
operationId: updateVolume
x-linode-cli-action: update
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
requestBody:
description: >
If any updated field fails to pass validation, the Volume will not be
updated.
required: true
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Volume'
- type: object
properties:
size:
readOnly: true
linode_id:
readOnly: true
responses:
'200':
description: The updated Volume.
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X PUT -d '{
"label": "my-volume"
}' \
https://api.linode.com/v4/volumes/12345
- lang: CLI
source: >
linode-cli volumes update 12345 \
--label my_volume
delete:
x-linode-grant: read_write
tags:
- Volumes
summary: Volume Delete
description: |
Deletes a Volume you have permission to `read_write`.
* **Deleting a Volume is a destructive action and cannot be undone.**
* Deleting stops billing for the Volume. You will be billed for time used within
the billing period the Volume was active.
* Volumes that are migrating cannot be deleted until the migration is finished.
operationId: deleteVolume
x-linode-cli-action: delete
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
responses:
'200':
description: Volume deletion successful.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X DELETE \
https://api.linode.com/v4/volumes/12345
- lang: CLI
source: >
linode-cli volumes delete 12345
/volumes/{volumeId}/attach:
parameters:
- name: volumeId
in: path
description: ID of the Volume to attach.
required: true
schema:
type: integer
x-linode-cli-command: volumes
post:
summary: Volume Attach
description: >
Attaches a Volume on your Account
to an existing Linode on your Account. In order for this request to
complete successfully, your User must have `read_only` or `read_write`
permission to the Volume and `read_write` permission to the Linode.
Additionally, the Volume and Linode must be located in the same Region.
tags:
- Volumes
operationId: attachVolume
x-linode-cli-action: attach
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
- linodes:read_write
requestBody:
description: Volume to attach to a Linode.
required: true
content:
application/json:
schema:
type: object
required:
- linode_id
properties:
linode_id:
type: integer
description: The ID of the Linode to attach the volume to.
config_id:
type: integer
description: >
The ID of the Linode Config to include this Volume in. Must
belong to the Linode referenced by `linode_id`. If not given,
the last booted Config will be chosen.
example: 23456
persist_across_boots:
type: boolean
description: >
Defaults to true, if false is provided, the Volume will
not be attached to the Linode Config. In this case more than
8 Volumes may be attached to a Linode if a Linode has
16GB of RAM or more. The number of volumes that can be
attached is equal to the number of GB of RAM that the
Linode has, up to a maximum of 64. `config_id` should not
be passed if this is set to false and linode_id must be
passed. The Linode must be running.
responses:
'200':
description: Volume was attached to a Linode.
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"linode_id": 12346,
"config_id": 23456
}' \
https://api.linode.com/v4/volumes/12345/attach
- lang: CLI
source: >
linode-cli volumes attach 12345 \
--linode_id 12346 \
--config_id 23456
/volumes/{volumeId}/clone:
parameters:
- name: volumeId
in: path
description: ID of the Volume to clone.
required: true
schema:
type: integer
x-linode-cli-command: volumes
post:
x-linode-charge: true
x-linode-grant: add_volumes
summary: Volume Clone
description: >
Creates a Volume on your Account. In
order for this request to complete successfully, your User must have the
`add_volumes` grant. The new Volume will have the same size and data as
the source Volume. Creating a new Volume will incur a charge on your
Account.
* Only Volumes with a `status` of "active" can be cloned.
tags:
- Volumes
operationId: cloneVolume
x-linode-cli-action: clone
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
requestBody:
description: The requested state your Volume will be cloned into.
required: true
content:
application/json:
schema:
type: object
required:
- label
properties:
label:
$ref: '#/components/schemas/Volume/properties/label'
responses:
'200':
description: Clone started.
content:
application/json:
schema:
$ref: '#/components/schemas/Volume'
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"label": "my-volume"
}' \
https://api.linode.com/v4/volumes/12345/clone
- lang: CLI
source: >
linode-cli volumes clone 12345 \
--label my-volume
/volumes/{volumeId}/detach:
parameters:
- name: volumeId
in: path
description: ID of the Volume to detach.
required: true
schema:
type: integer
x-linode-cli-command: volumes
post:
summary: Volume Detach
description: >
Detaches a Volume on your Account
from a Linode on your Account. In order for this request to
complete successfully, your User must have `read_write` access to the
Volume and `read_write` access to the Linode.
tags:
- Volumes
operationId: detachVolume
x-linode-cli-action: detach
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
- linodes:read_write
responses:
'200':
description: Volume was detached from a Linode.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST \
https://api.linode.com/v4/volumes/12345/detach
- lang: CLI
source: >
linode-cli volumes detach 12345
/volumes/{volumeId}/resize:
parameters:
- name: volumeId
in: path
description: ID of the Volume to resize.
required: true
schema:
type: integer
x-linode-cli-command: volumes
post:
x-linode-charge: true
summary: Volume Resize
description: >
Resize an existing Volume on your Account. In
order for this request to complete successfully, your User must have the
`read_write` permissions to the Volume.
* Volumes can only be resized up.
* Only Volumes with a `status` of "active" can be resized.
tags:
- Volumes
operationId: resizeVolume
x-linode-cli-action: resize
security:
- personalAccessToken: []
- oauth:
- volumes:read_write
requestBody:
description: The requested size to increase your Volume to.
required: true
content:
application/json:
schema:
type: object
required:
- size
properties:
size:
$ref: '#/components/schemas/Volume/properties/size'
responses:
'200':
description: Volume resize started.
content:
application/json:
schema:
type: object
default:
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Shell
source: >
curl -H "Content-Type: application/json" \
-H "Authorization: Bearer $TOKEN" \
-X POST -d '{
"size": 30
}' \
https://api.linode.com/v4/volumes/12345/resize
- lang: CLI
source: >
linode-cli volumes resize 12345 \
--size 30
components:
securitySchemes:
personalAccessToken:
type: http
scheme: bearer
oauth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: 'https://login.linode.com/oauth/authorize'
tokenUrl: 'https://login.linode.com/oauth/token'
scopes:
'account:read_only': Allows access to GET information about your Account.
'account:read_write': Allows access to all endpoints related to your Account.
'domains:read_only': Allows access to GET Domains on your Account.
'domains:read_write': Allows access to all Domain endpoints.
'events:read_only': Allows access to GET your Events.
'events:read_write': Allows access to all endpoints related to your Events.
'firewall:read_only': Allows access to GET information about your Firewalls.
'firewall:read_write': Allows acces to all Firewall endpoints.
'images:read_only': Allows access to GET your Images.
'images:read_write': Allows access to all endpoints related to your Images.
'ips:read_only': Allows access to GET your ips.
'ips:read_write': Allows access to all endpoints related to your ips.
'linodes:read_only': Allows access to GET Linodes on your Account.
'linodes:read_write': Allow access to all endpoints related to your Linodes.
'lke:read_only': Allows access to GET LKE Clusters on your Account.
'lke:read_write': Allows access to all endpoints related to LKE Clusters on your Account.
'longview:read_only': Allows access to GET your Longview Clients.
'longview:read_write': Allows access to all endpoints related to your Longview Clients.
'maintenance:read_only': Allows access to GET information about Maintenance on your account.
'nodebalancers:read_only': Allows access to GET NodeBalancers on your Account.
'nodebalancers:read_write': Allows access to all NodeBalancer endpoints.
'object_storage:read_only': Allows access to GET information related to your Object Storage.
'object_storage:read_write': Allows access to all Object Storage endpoints.
'stackscripts:read_only': Allows access to GET your StackScripts.
'stackscripts:read_write': Allows access to all endpoints related to your StackScripts.
'volumes:read_only': Allows access to GET your Volumes.
'volumes:read_write': Allows access to all endpoints related to your Volumes.
responses:
AcceptedResponse:
description: |
Accepted with warning.
A warnings array is included with the standard 200 response body.
content:
application/json:
schema:
type: object
properties:
warnings:
type: array
items:
$ref: '#/components/schemas/WarningObject'
DeprecatedResponse:
description: |
Request successful. This endpoint is deprecated and may be removed in a future release.
A warnings array is included with the standard 200 response body.
content:
application/json:
schema:
type: object
properties:
warnings:
type: array
items:
$ref: '#/components/schemas/WarningObject'
ErrorResponse:
description: Error
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorObject'
parameters:
pageOffset:
name: page
in: query
description: The page of a collection to return.
required: false
schema:
type: integer
minimum: 1
default: 1
pageSize:
name: page_size
in: query
description: The number of items to return per page.
schema:
type: integer
minimum: 25
maximum: 100
default: 100
links:
bootLinode:
operationId: bootLinodeInstance
parameters:
linodeId: '$request.body#/id'
rebootLinode:
operationId: rebootLinodeInstance
parameters:
linodeId: '$request.body#/id'
shutdownLinode:
operationId: shutdownLinodeInstance
parameters:
linodeId: '$request.body#/id'
updateLinode:
operationId: updateLinodeInstance
parameters:
linodeId: '$request.body#/id'
deleteLinode:
operationId: deleteLinodeInstance
parameters:
linodeId: '$request.body#/id'
rebuildLinode:
operationId: rebuildLinodeInstance
parameters:
linodeId: '$request.body#/id'
mutateLinode:
operationId: mutateLinodeInstance
parameters:
linodeId: '$request.body#/id'
resizeLinode:
operationId: resizeLinodeInstance
parameters:
linodeId: '$request.body#/id'
rescueLinode:
operationId: rescueLinodeInstance
parameters:
linodeId: '$request.body#/id'
cloneLinode:
operationId: cloneLinodeInstance
parameters:
linodeId: '$request.body#/id'
attachVolume:
operationId: attachVolume
parameters:
volumeID: '$request.body#/id'
cloneVolume:
operationId: cloneVolume
parameters:
volumeId: '$request.body#/id'
detachVolume:
operationId: detachVolume
parameters:
volumeId: '$request.body#/id'
resizeVolume:
operationId: resizeVolume
parameters:
volumeId: '$request.body#/id'
schemas:
Account:
type: object
description: Account object
properties:
active_promotions:
type: array
readOnly: true
items:
$ref: '#/components/schemas/Promotion'
active_since:
type: string
format: date-time
description: The datetime of when the account was activated.
example: '2018-01-01T00:01:01'
readOnly: true
address_1:
type: string
description: First line of this Account's billing address.
maxLength: 64
example: 123 Main Street
address_2:
type: string
description: Second line of this Account's billing address.
maxLength: 64
example: Suite A
balance:
type: number
readOnly: true
description: This Account's balance, in US dollars.
example: 200
x-linode-cli-display: 4
balance_uninvoiced:
type: number
readOnly: true
description: >
This Account's current estimated invoice in US dollars. This is not
your final invoice balance. Transfer charges are not included in
the estimate.
example: 145
x-linode-cli-display: 4
billing_source:
type: string
readOnly: true
enum:
- akamai
- linode
description: >
The source of service charges for this Account, as determined by its relationship with Akamai.
Accounts that are associated with Akamai-specific customers return a value of `akamai`.
All other Accounts return a value of `linode`.
example: akamai
capabilities:
type: array
items:
type: string
description: >
A list of capabilities your account supports.
example:
- Linodes
- NodeBalancers
- Block Storage
- Object Storage
readOnly: true
city:
type: string
description: The city for this Account's billing address.
maxLength: 24
example: Philadelphia
credit_card:
type: object
readOnly: true
description: Credit Card information associated with this Account.
properties:
last_four:
type: string
description: >
The last four digits of the credit card associated with this
Account.
example: 1111
expiry:
type: string
description: The expiration month and year of the credit card.
example: 11/2022
company:
type: string
description: The company name associated with this Account.
maxLength: 128
example: Linode LLC
country:
type: string
description: >
The two-letter ISO 3166 country code of this Account's billing address.
example: US
email:
type: string
description: The email address of the person associated with this Account.
maxLength: 128
example: john.smith@linode.com
x-linode-cli-display: 3
first_name:
type: string
description: The first name of the person associated with this Account.
maxLength: 50
example: John
x-linode-cli-display: 1
last_name:
type: string
description: The last name of the person associated with this Account.
maxLength: 50
example: Smith
x-linode-cli-display: 2
phone:
type: string
description: The phone number associated with this Account.
maxLength: 32
example: 215-555-1212
state:
type: string
description: >
If billing address is in the United States (US) or Canada (CA), only the two-letter
ISO 3166 State or Province code are accepted. If entering a US military address, state abbreviations (AA, AE, AP) should be entered. If the address is outside
the US or CA, this is the Province associated with the Account's billing
address.
maxLength: 24
example: PA
tax_id:
type: string
description: >
The tax identification number associated with this Account,
for tax calculations in some countries.
If you do not live in a country that collects tax, this should be an empty string (`""`).
maxLength: 25
example: ATU99999999
euuid:
type: string
description: >
An external unique identifier for this account.
format: uuid
readOnly: true
example: E1AF5EEC-526F-487D-B317EBEB34C87D71
zip:
type: string
description: |
The zip code of this Account's billing address. The following restrictions apply:
- May only consist of letters, numbers, spaces, and hyphens.
- Must not contain more than 9 letter or number characters.
example: 19102-1234
AccountSettings:
type: object
description: Account Settings object
properties:
managed:
type: boolean
readOnly: true
description: >
Our 24/7 incident response service. This robust, multi-homed
monitoring system distributes monitoring checks to ensure that your
servers remain online and available at all times. Linode Managed can
monitor any service or software stack reachable over TCP or HTTP.
Once you add a service to Linode Managed, we'll monitor it for
connectivity, response, and total request time.
example: true
x-linode-cli-display: 3
longview_subscription:
type: string
readOnly: true
description: >
The Longview Pro tier you are currently subscribed to. The value must be
a [Longview Subscription](/docs/api/longview/#longview-subscriptions-list)
ID or `null` for Longview Free.
example: longview-3
x-linode-cli-display: 2
network_helper:
type: boolean
description: >
Enables network helper across all users by default for
new Linodes and Linode Configs.
example: false
x-linode-cli-display: 1
backups_enabled:
type: boolean
description: >
Account-wide backups default. If `true`, all Linodes created will
automatically be enrolled in the Backups service. If `false`, Linodes
will not be enrolled by default, but may still be enrolled on creation
or later.
example: true
x-linode-cli-display: 4
object_storage:
type: string
readOnly: true
enum:
- disabled
- suspended
- active
description: >
A string describing the status of this account's Object Storage
service enrollment.
default: disabled
example: active
x-linode-cli-display: 5
AuthorizedApp:
type: object
description: >
An application you have authorized access to your Account through OAuth.
properties:
id:
type: integer
description: >
This authorization's ID, used for revoking access.
example: 123
readOnly: true
x-linode-cli-display: 1
label:
type: string
description: >
The name of the application you've authorized.
example: example-app
readOnly: true
x-linode-cli-display: 2
thumbnail_url:
type: string
format: url
description: >
The URL at which this app's thumbnail may be accessed.
example: null
readOnly: true
scopes:
type: string
format: oauth-scopes
description: >
The OAuth scopes this app was authorized with. This defines what parts of your
Account the app is allowed to access.
example: linodes:read_only
readOnly: true
x-linode-cli-display: 3
created:
type: string
format: date-time
description: When this app was authorized.
example: '2018-01-01T00:01:01'
readOnly: true
x-linode-filterable: true
x-linode-cli-display: 5
expiry:
type: string
format: date-time
description: >
When the app's access to your account expires. If `null`, the app's
access must be revoked manually.
example: '2018-01-15T00:01:01'
readOnly: true
x-linode-cli-display: 6
x-linode-filterable: true
nullable: true
website:
type: string
format: url
description: >
The website where you can get more information about this app.
example: example.org
readOnly: true
x-linode-cli-display: 4
Backup:
type: object
description: >
An object representing a Backup or snapshot for a Linode with Backup service
enabled.
properties:
id:
type: integer
readOnly: true
description: The unique ID of this Backup.
example: 123456
x-linode-cli-display: 1
type:
type: string
enum:
- auto
- snapshot
readOnly: true
description: >
This indicates whether the Backup is an automatic Backup or
manual snapshot taken by the User at a specific point in time.
example: snapshot
x-linode-cli-display: 3
status:
type: string
enum:
- paused
- pending
- running
- needsPostProcessing
- successful
- failed
- userAborted
readOnly: true
description: The current state of a specific Backup.
example: successful
x-linode-cli-display: 2
x-linode-cli-color:
successful: green
failed: red
userAborted: f
default_: yellow
created:
type: string
format: date-time
readOnly: true
description: The date the Backup was taken.
example: '2018-01-15T00:01:01'
x-linode-cli-display: 4
updated:
type: string
format: date-time
readOnly: true
description: The date the Backup was most recently updated.
example: '2018-01-15T00:01:01'
finished:
type: string
format: date-time
readOnly: true
description: The date the Backup completed.
example: '2018-01-15T00:01:01'
label:
type: string
description: A label for Backups that are of type `snapshot`.
example: Webserver-Backup-2018
x-linode-cli-display: 5
nullable: true
configs:
type: array
items:
type: string
example: My Debian 9 Config
readOnly: true
description: >
A list of the labels of the Configuration profiles that are part
of the Backup.
disks:
type: array
items:
type: object
properties:
size:
type: integer
example: 9001
filesystem:
$ref: '#/components/schemas/Disk/properties/filesystem'
label:
type: string
example: My Debian 9 Disk
readOnly: true
description: >
A list of the disks that are part of the Backup.
CreditCard:
type: object
description: |
An object representing the credit card information you have on file with
Linode to make Payments against your Account.
required:
- card_number
- expiry_month
- expiry_year
- cvv
properties:
card_number:
type: string
description: Your credit card number. No spaces or dashes allowed.
minLength: 14
maxLength: 24
format: digits
example: 4111111111111111
expiry_month:
type: integer
minimum: 1
maximum: 12
description: >
A value from 1-12 representing the expiration month of your credit card.
* 1 = January
* 2 = February
* 3 = March
* Etc.
example: 12
expiry_year:
type: integer
minLength: 4
maxLength: 4
description: |
A four-digit integer representing the expiration year of
your credit card.
The combination of `expiry_month` and `expiry_year`
must result in a month/year combination of the current month or in
the future. An expiration date set in the past is invalid.
example: 2020
cvv:
type: string
minLength: 3
maxLength: 4
format: digits
description: >
CVV (Card Verification Value) of the credit card, typically found on the back of the card.
example: '123'
Database:
type: object
description: A general Managed Database instance object containing properties that are identical for all database types.
properties:
id:
type: integer
description: A unique ID that can be used to identify and reference the Managed Database.
example: 123
x-linode-cli-display: 1
readOnly: true
label:
type: string
maxLength: 32
minLength: 3
x-linode-filterable: true
example: example-db
description: A unique, user-defined string referring to the Managed Database.
x-linode-cli-display: 2
type:
type: string
description: The Linode Instance type used by the Managed Database for its nodes.
example: g6-dedicated-2
x-linode-filterable: true
x-linode-cli-display: 4
engine:
type: string
enum:
- mongodb
- mysql
- postgresql
description: The Managed Database engine type.
example: mysql
x-linode-filterable: true
x-linode-cli-display: 6
readOnly: true
version:
type: string
description: The Managed Database engine version.
example: "8.0.26"
x-linode-filterable: true
x-linode-cli-display: 7
readOnly: true
region:
type: string
description: The [Region](/docs/api/regions/) ID for the Managed Database.
example: us-east
x-linode-filterable: true
x-linode-cli-display: 3
status:
type: string
enum:
- provisioning
- active
- suspending
- suspended
- resuming
- restoring
- failed
- degraded
- updating
- backing_up
description: The operating status of the Managed Database.
example: active
x-linode-filterable: true
x-linode-cli-display: 100
x-linode-cli-color:
provisioning: yellow
active: green
resuming: yellow
restoring: yellow
failed: red
degraded: red
updating: yellow
default_: white
readOnly: true
encrypted:
type: boolean
default: false
description: Whether the Managed Databases is encrypted.
example: false
allow_list:
type: array
example:
- "203.0.113.1/32"
- "192.0.1.0/24"
description: |
A list of IP addresses that can access the Managed Database. Each item can be a single IP address or a range in CIDR format.
By default, this is an empty array (`[]`), which blocks all connections (both public and private) to the Managed Database.
items:
type: string
format: ipv4/prefix_length
pattern: '^([0-9]{1,3}\.){3}[0-9]{1,3}(\/([0-9]|[1-2][0-9]|3[0-2]))?$'
cluster_size:
type: integer
enum:
- 1
- 3
example: 3
default: 1
description: |
The number of Linode Instance nodes deployed to the Managed Database.
Choosing 3 nodes creates a high availability cluster consisting of 1 primary node and 2 replica nodes.
x-linode-cli-display: 5
hosts:
type: object
readOnly: true
description: The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.
properties:
primary:
type: string
description: The primary host for the Managed Database.
example: lin-123-456-mysql-mysql-primary.servers.linodedb.net
nullable: true
secondary:
type: string
description: |
The secondary/private network host for the Managed Database.
A private network host and a private IP can only be used to access a Database Cluster from Linodes in the same data center and will not incur transfer costs.
**Note**: The secondary hostname is publicly viewable and accessible.
example: lin-123-456-mysql-primary-private.servers.linodedb.net
nullable: true
created:
type: string
format: date-time
description: When this Managed Database was created.
example: '2022-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Managed Database was last updated.
example: '2022-01-01T00:01:01'
readOnly: true
updates:
type: object
description: Configuration settings for automated patch update maintenance for the Managed Database.
properties:
frequency:
type: string
default: weekly
enum:
- weekly
- monthly
description: Whether maintenance occurs on a weekly or monthly basis.
example: weekly
duration:
type: integer
minimum: 1
maximum: 3
description: The maximum maintenance window time in hours.
example: 3
hour_of_day:
type: integer
minimum: 0
maximum: 23
description: The hour to begin maintenance based in UTC time.
example: 0
day_of_week:
type: integer
minimum: 1
maximum: 7
description: The day to perform maintenance. 1=Monday, 2=Tuesday, etc.
example: 1
week_of_month:
type: integer
minimum: 1
maximum: 4
nullable: true
description: |
The week of the month to perform `monthly` frequency updates. Defaults to `null`.
* Required for `monthly` frequency updates.
* Must be `null` for `weekly` frequency updates.
example: null
instance_uri:
type: string
example: "/v4/databases/mysql/instances/123"
description: |
Append this to `https://api.linode.com` to run commands for the Managed Database.
readOnly: true
DatabaseBackup:
type: object
description: A database backup object.
properties:
id:
type: integer
description: The ID of the database backup object.
example: 123
x-linode-cli-display: 1
type:
type: string
enum:
- snapshot
- auto
description: The type of database backup, determined by how the backup was created.
example: auto
x-linode-filterable: true
x-linode-cli-display: 3
label:
type: string
maxLength: 30
description: |
The database backup's label, for display purposes only.
Must include only ASCII letters or numbers.
example: Scheduled - 02/04/22 11:11 UTC-XcCRmI
x-linode-cli-display: 2
created:
type: string
format: datetime
example: '2022-01-01T00:01:01'
description: A time value given in a combined date and time format that represents when the database backup was created.
x-linode-filterable: true
x-linode-cli-display: 4
DatabaseCredentials:
type: object
description: Managed Database object for database credentials.
properties:
username:
type: string
readOnly: true
description: The root username for the Managed Database instance.
example: linroot
x-linode-cli-display: 1
password:
type: string
readOnly: true
description: The randomly-generated root password for the Managed Database instance.
example: s3cur3P@ssw0rd
x-linode-cli-display: 2
DatabaseEngine:
type: object
description: Managed Database engine object.
properties:
id:
type: string
example: mysql/8.0.26
description: The Managed Database engine ID in engine/version format.
x-linode-cli-display: 1
engine:
type: string
example: mysql
description: The Managed Database engine type.
x-linode-filterable: true
x-linode-cli-display: 2
version:
type: string
example: "8.0.26"
description: The Managed Database engine version.
x-linode-filterable: true
x-linode-cli-display: 3
DatabaseMongoDB:
type: object
description: Managed MongoDB Databases object.
properties:
id:
$ref: '#/components/schemas/Database/properties/id'
x-linode-cli-display: 1
label:
$ref: '#/components/schemas/Database/properties/label'
x-linode-cli-display: 2
type:
$ref: '#/components/schemas/Database/properties/type'
x-linode-cli-display: 4
engine:
type: string
description: The Managed Database engine type.
example: mongodb
x-linode-filterable: true
x-linode-cli-display: 6
readOnly: true
version:
type: string
description: The Managed Database engine version.
example: "4.4.10"
x-linode-filterable: true
x-linode-cli-display: 7
readOnly: true
region:
$ref: '#/components/schemas/Database/properties/region'
x-linode-cli-display: 3
status:
$ref: '#/components/schemas/Database/properties/status'
x-linode-cli-display: 100
x-linode-cli-color:
provisioning: yellow
active: green
resuming: yellow
restoring: yellow
failed: red
degraded: red
default_: white
encrypted:
$ref: '#/components/schemas/Database/properties/encrypted'
allow_list:
$ref: '#/components/schemas/Database/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/Database/properties/cluster_size'
x-linode-cli-display: 5
hosts:
type: object
readOnly: true
description: The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.
properties:
primary:
type: string
description: The primary host for the Managed Database.
example: lin-0000-0000.servers.linodedb.net
nullable: true
secondary:
type: string
description: |
The secondary/private network host for the Managed Database.
A private network host and a private IP can only be used to access a Database Cluster from Linodes in the same data center and will not incur transfer costs.
**Note**: The secondary hostname is publicly viewable and accessible.
example: null
nullable: true
peers:
type: array
description: |
An array of peer addresses for this Database.
items:
type: string
description: |
The peer address of a Managed MongoDB Database cluster node. Each node in a cluster has its own unique peer address.
example:
- lin-0000-0000.servers.linodedb.net
- lin-0000-0001.servers.linodedb.net
- lin-0000-0002.servers.linodedb.net
replica_set:
nullable: true
default: null
type: string
maxLength: 64
description: |
Label for configuring a MongoDB [replica set](https://www.mongodb.com/docs/manual/replication/). Choose the same label on multiple Databases to include them in the same replica set.
If `null`, the Database is not included in any replica set.
example: null
ssl_connection:
type: boolean
default: true
example: true
description: |
Whether to require SSL credentials to establish a connection to the Managed Database.
Use the **Managed MongoDB Database Credentials View** ([GET /databases/mongodb/instances/{instanceId}/credentials](/docs/api/databases/#managed-mongodb-database-credentials-view)) command for access information.
compression_type:
type: string
enum:
- none
- snappy
- zlip
default: none
example: none
description: |
The type of data compression for this Database.
Snappy has a lower comparative compression ratio and resource consumption rate.
Zlip has a higher comparative compression ratio and resource consumption rate.
x-linode-cli-display: 99
storage_engine:
type: string
enum:
- mmapv1
- wiredtiger
default: wiredtiger
example: wiredtiger
description: |
The type of storage engine for this Database.
**Note:** MMAPV1 is not available for MongoDB versions 4.0 and above.
port:
type: integer
description: The access port for this Managed Database.
example: 27017
x-linode-cli-display: 98
created:
$ref: '#/components/schemas/Database/properties/created'
updated:
$ref: '#/components/schemas/Database/properties/updated'
updates:
$ref: '#/components/schemas/Database/properties/updates'
DatabaseMongoDBRequest:
type: object
description: Managed MongoDB Database request object.
required:
- label
- type
- engine
- region
properties:
label:
$ref: '#/components/schemas/DatabaseMongoDB/properties/label'
type:
$ref: '#/components/schemas/DatabaseMongoDB/properties/type'
engine:
type: string
example: mongodb/4.4.10
description: The Managed Database engine in engine/version format.
region:
$ref: '#/components/schemas/DatabaseMongoDB/properties/region'
encrypted:
$ref: '#/components/schemas/DatabaseMongoDB/properties/encrypted'
allow_list:
$ref: '#/components/schemas/DatabaseMongoDB/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/DatabaseMongoDB/properties/cluster_size'
replica_set:
$ref: '#/components/schemas/DatabaseMongoDB/properties/replica_set'
ssl_connection:
$ref: '#/components/schemas/DatabaseMongoDB/properties/ssl_connection'
compression_type:
$ref: '#/components/schemas/DatabaseMongoDB/properties/compression_type'
storage_engine:
$ref: '#/components/schemas/DatabaseMongoDB/properties/storage_engine'
DatabaseMySQL:
type: object
description: Managed MySQL Databases object.
properties:
id:
$ref: '#/components/schemas/Database/properties/id'
x-linode-cli-display: 1
label:
$ref: '#/components/schemas/Database/properties/label'
x-linode-cli-display: 2
type:
$ref: '#/components/schemas/Database/properties/type'
x-linode-cli-display: 4
engine:
type: string
description: The Managed Database engine type.
example: mysql
x-linode-filterable: true
x-linode-cli-display: 6
readOnly: true
version:
type: string
description: The Managed Database engine version.
example: "8.0.26"
x-linode-filterable: true
x-linode-cli-display: 7
readOnly: true
region:
$ref: '#/components/schemas/Database/properties/region'
x-linode-cli-display: 3
status:
$ref: '#/components/schemas/Database/properties/status'
x-linode-cli-display: 100
x-linode-cli-color:
provisioning: yellow
active: green
resuming: yellow
restoring: yellow
failed: red
degraded: red
default_: white
encrypted:
$ref: '#/components/schemas/Database/properties/encrypted'
allow_list:
$ref: '#/components/schemas/Database/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/Database/properties/cluster_size'
x-linode-cli-display: 5
hosts:
$ref: '#/components/schemas/Database/properties/hosts'
ssl_connection:
type: boolean
default: true
example: true
description: |
Whether to require SSL credentials to establish a connection to the Managed Database.
Use the **Managed MySQL Database Credentials View** ([GET /databases/mysql/instances/{instanceId}/credentials](/docs/api/databases/#managed-mysql-database-credentials-view)) command for access information.
replication_type:
type: string
enum:
- none
- asynch
- semi_synch
example: semi_synch
description: |
The replication method used for the Managed Database.
Defaults to `none` for a single cluster and `semi_synch` for a high availability cluster.
Must be `none` for a single node cluster.
Must be `asynch` or `semi_synch` for a high availability cluster.
x-linode-cli-display: 99
port:
type: integer
description: The access port for this Managed Database.
example: 3306
x-linode-cli-display: 98
created:
$ref: '#/components/schemas/Database/properties/created'
updated:
$ref: '#/components/schemas/Database/properties/updated'
updates:
$ref: '#/components/schemas/Database/properties/updates'
DatabaseMySQLRequest:
type: object
description: Managed MySQL Database request object.
required:
- label
- type
- engine
- region
properties:
label:
$ref: '#/components/schemas/DatabaseMySQL/properties/label'
type:
$ref: '#/components/schemas/DatabaseMySQL/properties/type'
engine:
type: string
example: mysql/8.0.26
description: The Managed Database engine in engine/version format.
region:
$ref: '#/components/schemas/DatabaseMySQL/properties/region'
encrypted:
$ref: '#/components/schemas/DatabaseMySQL/properties/encrypted'
allow_list:
$ref: '#/components/schemas/DatabaseMySQL/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/DatabaseMySQL/properties/cluster_size'
ssl_connection:
$ref: '#/components/schemas/DatabaseMySQL/properties/ssl_connection'
replication_type:
$ref: '#/components/schemas/DatabaseMySQL/properties/replication_type'
DatabasePostgreSQL:
type: object
description: Managed PostgreSQL Databases object.
properties:
id:
$ref: '#/components/schemas/Database/properties/id'
x-linode-cli-display: 1
label:
$ref: '#/components/schemas/Database/properties/label'
x-linode-cli-display: 2
type:
$ref: '#/components/schemas/Database/properties/type'
x-linode-cli-display: 4
engine:
type: string
description: The Managed Database engine type.
example: postgresql
x-linode-filterable: true
x-linode-cli-display: 6
readOnly: true
version:
type: string
description: The Managed Database engine version.
example: "13.2"
x-linode-filterable: true
x-linode-cli-display: 7
readOnly: true
region:
$ref: '#/components/schemas/Database/properties/region'
x-linode-cli-display: 3
status:
$ref: '#/components/schemas/Database/properties/status'
x-linode-cli-display: 100
x-linode-cli-color:
provisioning: yellow
active: green
resuming: yellow
restoring: yellow
failed: red
degraded: red
default_: white
encrypted:
$ref: '#/components/schemas/Database/properties/encrypted'
allow_list:
$ref: '#/components/schemas/Database/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/Database/properties/cluster_size'
x-linode-cli-display: 5
hosts:
type: object
readOnly: true
description: The primary and secondary hosts for the Managed Database. These are assigned after provisioning is complete.
properties:
primary:
type: string
description: The primary host for the Managed Database.
example: lin-0000-000-pgsql-primary.servers.linodedb.net
nullable: true
secondary:
type: string
description: |
The secondary/private network host for the Managed Database.
A private network host and a private IP can only be used to access a Database Cluster from Linodes in the same data center and will not incur transfer costs.
**Note**: The secondary hostname is publicly viewable and accessible.
example: lin-0000-000-pgsql-primary-private.servers.linodedb.net
nullable: true
ssl_connection:
type: boolean
default: true
example: true
description: |
Whether to require SSL credentials to establish a connection to the Managed Database.
Use the **Managed PostgreSQL Database Credentials View** ([GET /databases/postgresql/instances/{instanceId}/credentials](/docs/api/databases/#managed-postgresql-database-credentials-view)) command for access information.
replication_type:
type: string
enum:
- none
- asynch
- semi_synch
example: semi_synch
description: |
The replication method used for the Managed Database.
Defaults to `none` for a single cluster and `semi_synch` for a high availability cluster.
Must be `none` for a single node cluster.
Must be `asynch` or `semi_synch` for a high availability cluster.
x-linode-cli-display: 99
replication_commit_type:
type: string
enum:
- 'on'
- 'local'
- 'remote_write'
- 'remote_apply'
- 'off'
default: local
example: local
description: |
The synchronization level of the replicating server.
Must be `local` or `off` for the `asynch` replication type.
Must be `on`, `remote_write`, or `remote_apply` for the `semi_synch` replication type.
x-linode-cli-display: 100
port:
type: integer
description: The access port for this Managed Database.
example: 3306
x-linode-cli-display: 98
created:
$ref: '#/components/schemas/Database/properties/created'
updated:
$ref: '#/components/schemas/Database/properties/updated'
updates:
$ref: '#/components/schemas/Database/properties/updates'
DatabasePostgreSQLRequest:
type: object
description: Managed PostgreSQL Database request object.
required:
- label
- type
- engine
- region
properties:
label:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/label'
type:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/type'
engine:
type: string
example: postgresql/13.2
description: The Managed Database engine in engine/version format.
region:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/region'
encrypted:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/encrypted'
allow_list:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/allow_list'
cluster_size:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/cluster_size'
ssl_connection:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/ssl_connection'
replication_type:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/replication_type'
replication_commit_type:
$ref: '#/components/schemas/DatabasePostgreSQL/properties/replication_commit_type'
DatabaseSSL:
type: object
description: Managed Database SSL object.
properties:
ca_certificate:
type: string
format: base64
description: The base64-encoded SSL CA certificate for the Managed Database instance.
example: LS0tLS1CRUdJ...==
x-linode-cli-display: 1
DatabaseType:
type: object
description: Managed Database plan type object.
properties:
id:
type: string
description: The ID representing the Managed Database node plan type.
readOnly: true
example: g6-nanode-1
x-linode-cli-display: 1
label:
type: string
description: A human-readable string that describes each plan type. For display purposes only.
readOnly: true
example: DBaaS - Nanode 1GB
x-linode-cli-display: 2
engines:
type: object
properties:
mysql:
type: array
description: Pricing details for MySQL Managed Databases.
items:
$ref: '#/components/schemas/DatabaseTypeEngine'
postgresql:
type: array
description: Pricing details for PostgreSQL Managed Databases.
items:
$ref: '#/components/schemas/DatabaseTypeEngine'
mongodb:
type: array
description: Pricing details for MongoDB Managed Databases.
items:
$ref: '#/components/schemas/DatabaseTypeEngine'
memory:
type: integer
description: The amount of RAM allocated to Database created of this plan type. The value is represented in megabytes.
example: 1024
x-linode-cli-display: 3
disk:
type: integer
description: The amount of disk space set aside for Databases of this plan type. The value is represented in megabytes.
example: 25600
x-linode-cli-display: 4
vcpus:
type: integer
description: The integer of number CPUs allocated to databases of this plan type.
example: 1
x-linode-cli-display: 5
deprecated:
type: boolean
description: Whether this Database plan type has been deprecated and is no longer available.
example: false
x-linode-filterable: true
x-linode-cli-display: 6
class:
type: string
description: The compute class category.
example: nanode
DatabaseTypeEngine:
type: object
properties:
quantity:
type: integer
enum:
- 1
- 2
- 3
description: The number of nodes for the Managed Database cluster for this subscription tier.
example: 1
price:
type: object
description: Cost in US dollars, broken down into hourly and monthly charges.
properties:
hourly:
type: number
description: Cost (in US dollars) per hour for this subscription tier.
example: 0.03
monthly:
type: number
description: Maximum cost (in US dollars) per month for this subscription tier.
example: 20
Device:
type: object
description: >
Device can be either a Disk or Volume identified by `disk_id` or
`volume_id`. Only one type per slot allowed. Can be null.
Devices mapped from _sde_ through _sdh_ are unavailable in `fullvirt` virt_mode.
properties:
disk_id:
type: integer
description: The Disk ID, or `null` if a Volume is assigned to this slot.
example: 124458
volume_id:
type: integer
description: The Volume ID, or `null` if a Disk is assigned to this slot.
example: null
Devices:
type: object
description: >
A dictionary of device disks to use as a device map in a Linode's configuration profile.
* An empty device disk dictionary or a dictionary with empty values for device slots is allowed.
* If no devices are specified, booting from this configuration will hold until a device exists that allows the boot process to start.
properties:
sda:
$ref: '#/components/schemas/Device'
sdb:
$ref: '#/components/schemas/Device'
sdc:
$ref: '#/components/schemas/Device'
sdd:
$ref: '#/components/schemas/Device'
sde:
$ref: '#/components/schemas/Device'
sdf:
$ref: '#/components/schemas/Device'
sdg:
$ref: '#/components/schemas/Device'
sdh:
$ref: '#/components/schemas/Device'
Disk:
type: object
properties:
id:
type: integer
description: >
This Disk's ID which must be provided for all
operations impacting this Disk.
example: 25674
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
description: >
The Disk's label is for display purposes only.
example: Debian 9 Disk
minLength: 1
maxLength: 48
x-linode-cli-display: 2
status:
type: string
description: >
A brief description of this Disk's current state. This field may change without
direct action from you, as a result of operations performed to the Disk
or the Linode containing the Disk.
example: ready
readOnly: true
enum:
- ready
- not ready
- deleting
x-linode-cli-display: 3
x-linode-cli-color:
ready: green
not ready: red
default_: yellow
size:
x-linode-filterable: true
type: integer
description: The size of the Disk in MB.
example: 48640
x-linode-cli-display: 4
filesystem:
type: string
description: >
The Disk filesystem can be one of:
* raw - No filesystem, just a raw binary stream.
* swap - Linux swap area.
* ext3 - The ext3 journaling filesystem for Linux.
* ext4 - The ext4 journaling filesystem for Linux.
* initrd - initrd (uncompressed initrd, ext2, max 32 MB).
example: ext4
enum:
- raw
- swap
- ext3
- ext4
- initrd
x-linode-cli-display: 5
created:
type: string
format: date-time
description: When this Disk was created.
example: '2018-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Disk was last updated.
example: '2018-01-01T00:01:01'
readOnly: true
DiskRequest:
type: object
description: Disk object request.
properties:
size:
x-linode-filterable: true
type: integer
description: |
The size of the Disk in MB.
Images require a minimum size. Access the Image View ([GET /images/{imageID}](/docs/api/images/#image-view)) endpoint to view its size.
example: 48640
label:
$ref: '#/components/schemas/Disk/properties/label'
filesystem:
$ref: '#/components/schemas/Disk/properties/filesystem'
image:
type: string
description: |
An Image ID to deploy the Linode Disk from.
Access the Images List ([GET /images](/docs/api/images/#images-list)) endpoint with authentication to view
all available Images. Official Linode Images start with `linode/`, while your Account's Images start with `private/`. Creating
a disk from a Private Image requires `read_only` or `read_write` permissions for that Image. Access the User's
Grant Update ([PUT /account/users/{username}/grants](/docs/api/account/#users-grants-update)) endpoint to
adjust permissions for an Account Image.
example: linode/debian9
authorized_keys:
type: array
items:
type: string
writeOnly: true
example:
- ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer
description: |
A list of public SSH keys that will be automatically appended
to the root user's `~/.ssh/authorized_keys` file when deploying from an Image.
authorized_users:
type: array
items:
type: string
writeOnly: true
example:
- myUser
- secondaryUser
description: >
A list of usernames. If the usernames have associated
SSH keys, the keys will be appended to the root users
`~/.ssh/authorized_keys` file automatically when deploying from an Image.
root_pass:
type: string
format: password
writeOnly: true
example: aComplexP@ssword
minLength: 7
maxLength: 128
description: |
This sets the root user's password on a newly-created Linode Disk when deploying from an Image.
* **Required** when creating a Linode Disk from an Image, including when using a StackScript.
* Must meet a password strength score requirement that is calculated internally by the API.
If the strength requirement is not met, you will receive a `Password does not meet strength requirement` error.
stackscript_id:
type: integer
example: 10079
description: |
A StackScript ID that will cause the referenced StackScript to be run during
deployment of this Linode. A compatible `image` is required to use a
StackScript. To get a list of available StackScript and their permitted Images
see [/stackscripts](/docs/api/stackscripts/#stackscripts-list).
This field cannot be used when deploying from a Backup or a Private Image.
stackscript_data:
type: object
example:
gh_username: linode
description: |
This field is required only if the StackScript being deployed requires input
data from the User for successful completion. See
[User Defined Fields (UDFs)](/docs/guides/writing-scripts-for-use-with-linode-stackscripts-a-tutorial/#user-defined-fields-udfs)
for more details. This field is required to be valid JSON.
Domain:
type: object
description: >
A domain zonefile in our DNS system. You must own the domain name and
tell your registrar to use Linode's nameservers in order for a domain
in our system to be treated as authoritative.
properties:
id:
type: integer
description: This Domain's unique ID
example: 1234
readOnly: true
x-linode-cli-display: 1
type:
type: string
enum:
- master
- slave
description: >
Whether this Domain represents the authoritative source of information for the domain
it describes ("master"), or whether it is a read-only copy of a master ("slave").
example: master
x-linode-cli-display: 3
domain:
type: string
pattern: \A(\*\.)?([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)\Z
minLength: 1
maxLength: 255
description: >
The domain this Domain represents. Domain labels cannot be longer than
63 characters and must conform to [RFC1035](https://tools.ietf.org/html/rfc1035).
Domains must be unique on Linode's platform, including across different Linode
accounts; there cannot be two Domains representing the same domain.
example: example.org
x-linode-filterable: true
x-linode-cli-display: 2
group:
deprecated: true
type: string
description: >
The group this Domain belongs to. This is for display purposes
only.
example: null
minLength: 1
maxLength: 50
x-linode-filterable: true
status:
type: string
enum:
- disabled
- active
default: active
description: >
Used to control whether this Domain is currently being rendered.
example: active
x-linode-cli-display: 4
x-linode-cli-color:
active: green
disabled: yellow
edit_mode: yellow
default_: red
description:
type: string
minLength: 1
maxLength: 255
description: |
A description for this Domain. This is for display purposes only.
example: null
soa_email:
type: string
format: email
description: >
Start of Authority email address. This is required for `type` master
Domains.
example: admin@example.org
x-linode-cli-display: 5
retry_sec:
type: integer
default: 0
description: |
The interval, in seconds, at which a failed refresh should be retried.
* Valid values are
0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
* Any other value is rounded up to the nearest valid value.
* A value of 0 is equivalent to the default value of 14400.
example: 300
master_ips:
type: array
items:
type: string
format: ip
description: >
The IP addresses representing the master DNS for this Domain. At least one value is required for `type` slave Domains. The total combined length of all data within this array cannot exceed 1000 characters.
example: []
axfr_ips:
type: array
items:
type: string
format: ip
description: |
The list of IPs that may perform a zone transfer for this Domain. The total combined length of all data within this array cannot exceed 1000 characters.
**Note**: This is potentially dangerous, and should be set to an empty list unless you intend to use it.
example: []
expire_sec:
type: integer
default: 0
description: |
The amount of time in seconds that may pass before this Domain is no longer
authoritative.
* Valid values are
0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
* Any other value is rounded up to the nearest valid value.
* A value of 0 is equivalent to the default value of 1209600.
example: 300
refresh_sec:
type: integer
default: 0
description: |
The amount of time in seconds before this Domain should be refreshed.
* Valid values are
0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
* Any other value is rounded up to the nearest valid value.
* A value of 0 is equivalent to the default value of 14400.
example: 300
ttl_sec:
type: integer
default: 0
description: >
"Time to Live" - the amount of time in seconds that this Domain's
records may be cached by resolvers or other domain servers.
* Valid values are
0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200.
* Any other value is rounded up to the nearest valid value.
* A value of 0 is equivalent to the default value of 86400.
example: 300
tags:
x-linode-filterable: true
description: >
An array of tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
DomainRecord:
type: object
description: >
A single record on a Domain.
properties:
id:
type: integer
description: This Record's unique ID.
example: 123456
readOnly: true
x-linode-cli-display: 1
type:
type: string
enum:
- A
- AAAA
- NS
- MX
- CNAME
- TXT
- SRV
- PTR
- CAA
description: >
The type of Record this is in the DNS system. For example, A
records associate a domain name with an IPv4 address, and AAAA
records associate a domain name with an IPv6 address. For more information, see our guide on
[DNS Records](/docs/guides/dns-records-an-introduction).
example: A
x-linode-filterable: true
x-linode-cli-display: 2
name:
type: string
description: |
The name of this Record. For requests, this property's actual usage and whether it is required depends
on the type of record this represents:
`A` and `AAAA`: The hostname or FQDN of the Record.
`NS`: The subdomain, if any, to use with the Domain of the Record.
`MX`: The mail subdomain. For example, `sub` for the address `user@sub.example.com` under the `example.com`
Domain. Must be an empty string (`""`) for a Null MX Record.
`CNAME`: The hostname. Must be unique. Required.
`TXT`: The hostname.
`SRV`: Unused. Use the `service` property to set the service name for this record.
`CAA`: The subdomain. Omit or enter an empty string (`""`) to apply to the entire Domain.
`PTR`: See our guide on how to [Configure Your Linode for Reverse DNS
(rDNS)](/docs/guides/configure-your-linode-for-reverse-dns).
minLength: 1
maxLength: 100
example: test
x-linode-filterable: true
x-linode-cli-display: 3
target:
type: string
description: |
The target for this Record. For requests, this property's actual usage and whether it is required depends
on the type of record this represents:
`A` and `AAAA`: The IP address. Use `[remote_addr]` to submit the IPv4 address of the request. Required.
`NS`: The name server. Must be a valid domain. Required.
`MX`: The mail server. Must be a valid domain unless creating a Null MX Record. To create a
[Null MX Record](https://datatracker.ietf.org/doc/html/rfc7505), first
[remove](/docs/api/domains/#domain-record-delete) any additional MX records, create an MX record with empty strings
(`""`) for the `target` and `name`. If a Domain has a Null MX record, new MX records cannot be created. Required.
`CNAME`: The alias. Must be a valid domain. Required.
`TXT`: The value. Required.
`SRV`: The target domain or subdomain. If a subdomain is entered, it is automatically used with the Domain.
To configure for a different domain, enter a valid FQDN. For example, the value `www` with a Domain for
`example.com` results in a target set to `www.example.com`, whereas the value `sample.com` results in a
target set to `sample.com`. Required.
`CAA`: The value. For `issue` or `issuewild` tags, the domain of your certificate issuer. For the `iodef`
tag, a contact or submission URL (domain, http, https, or mailto). Requirements depend on the tag for this record:
* `issue`: The domain of your certificate issuer. Must be a valid domain.
* `issuewild`: Must begin with `*`.
* `iodef`: Must be either (1) a valid domain, (2) a valid domain prepended with `http://` or `https://`, or (3) a valid email address prepended with `mailto:`.
`PTR`: Required. See our guide on how to [Configure Your Linode for Reverse DNS
(rDNS)](/docs/guides/configure-your-linode-for-reverse-dns).
With the exception of A, AAAA, and CAA records, this field accepts a trailing period.
example: 192.0.2.0
x-linode-filterable: true
x-linode-cli-display: 4
priority:
type: integer
minimum: 0
maximum: 255
description: |
The priority of the target host for this Record. Lower values are preferred. Only valid for
MX and SRV record requests. Required for SRV record requests.
Defaults to `0` for MX record requests. Must be `0` for Null MX records.
example: 50
x-linode-cli-display: 6
weight:
type: integer
description: >
The relative weight of this Record used in the case of identical priority. Higher values are preferred.
Only valid and required for SRV record requests.
example: 50
minimum: 0
maximum: 65535
x-linode-cli-display: 7
port:
type: integer
description: >
The port this Record points to. Only valid and required for SRV record requests.
example: 80
minimum: 0
maximum: 65535
service:
type: string
nullable: true
description: >
The name of the service. An underscore (`_`) is prepended and a period (`.`) is appended automatically to the
submitted value for this property. Only valid and required for SRV record requests.
example: null
protocol:
type: string
nullable: true
description: >
The protocol this Record's service communicates with. An underscore (`_`) is prepended
automatically to the submitted value for this property. Only valid
for SRV record requests.
example: null
ttl_sec:
type: integer
description: >
"Time to Live" - the amount of time in seconds that this Domain's
records may be cached by resolvers or other domain servers. Valid
values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800,
345600, 604800, 1209600, and 2419200 - any other value will be
rounded to the nearest valid value.
example: 604800
x-linode-cli-display: 5
tag:
type: string
enum:
- issue
- issuewild
- iodef
nullable: true
description: >
The tag portion of a CAA record. Only valid and required for CAA record requests.
example: null
x-linode-filterable: true
created:
type: string
format: date-time
description: When this Domain Record was created.
example: '2018-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Domain Record was last updated.
example: '2018-01-01T00:01:01'
readOnly: true
EntityTransfer:
type: object
description: >
An object representing an Entity Transfer.
properties:
token:
x-linode-cli-display: 1
type: string
format: uuid
description: >
The token used to identify and accept or cancel this transfer.
example: "123E4567-E89B-12D3-A456-426614174000"
status:
x-linode-cli-display: 2
x-linode-filterable: true
x-linode-cli-color:
accepted: yellow
cancelled: red
completed: green
failed: red
pending: yellow
stale: red
default_: white
type: string
enum:
- accepted
- cancelled
- completed
- failed
- pending
- stale
description: >
The status of the transfer request.
`accepted`: The transfer has been accepted by another user and is currently in progress.
Transfers can take up to 3 hours to complete.
`cancelled`: The transfer has been cancelled by the sender.
`completed`: The transfer has completed successfully.
`failed`: The transfer has failed after initiation.
`pending`: The transfer is ready to be accepted.
`stale`: The transfer has exceeded its expiration date. It can no longer be accepted or
cancelled.
example: 'pending'
created:
type: string
format: date-time
description: >
When this transfer was created.
example: '2021-02-11T16:37:03'
updated:
type: string
format: date-time
description: >
When this transfer was last updated.
example: '2021-02-11T16:37:03'
is_sender:
x-linode-cli-display: 4
x-linode-filterable: true
type: boolean
description: >
If the requesting account created this transfer.
example: true
expiry:
x-linode-cli-display: 3
type: string
format: date-time
description: >
When this transfer expires. Transfers will automatically expire 24 hours after creation.
example: '2021-02-12T16:37:03'
entities:
type: object
description: >
A collection of the entities to include in this transfer request, separated by type.
properties:
linodes:
x-linode-cli-display: 5
type: array
items:
type: integer
description: >
An array containing the IDs of each of the Linodes included in this transfer.
example: [111, 222]
ErrorObject:
type: object
description: >
An object for describing a single error that occurred during the processing of a request.
properties:
reason:
type: string
description: >
What happened to cause this error. In most cases, this can be fixed immediately by
changing the data you sent in the request, but in some cases you will be instructed to
[open a Support Ticket](/docs/api/support/#support-ticket-open) or perform some
other action before you can complete the request successfully.
example: fieldname must be a valid value
field:
type: string
description: >
The field in the request that caused this error. This may be a path, separated by
periods in the case of nested fields. In some cases this may come back as "null" if the
error is not specific to any single element of the request.
example: fieldname
Event:
type: object
description: >
A collection of Event objects. An Event is an action taken against an
entity related to your Account. For example, booting a Linode would
create an Event.
The Events returned depends on your grants.
properties:
id:
type: integer
readOnly: true
description: The unique ID of this Event.
example: 123
x-linode-cli-display: 1
x-linode-filterable: true
action:
type: string
enum:
- account_update
- account_settings_update
- backups_enable
- backups_cancel
- backups_restore
- community_question_reply
- community_like
- credit_card_updated
- disk_create
- disk_delete
- disk_update
- disk_duplicate
- disk_imagize
- disk_resize
- dns_record_create
- dns_record_delete
- dns_record_update
- dns_zone_create
- dns_zone_delete
- dns_zone_import
- dns_zone_update
- entity_transfer_accept
- entity_transfer_cancel
- entity_transfer_create
- entity_transfer_fail
- entity_transfer_stale
- firewall_create
- firewall_delete
- firewall_disable
- firewall_enable
- firewall_update
- firewall_device_add
- firewall_device_remove
- host_reboot
- image_delete
- image_update
- image_upload
- ipaddress_update
- lassie_reboot
- lish_boot
- linode_addip
- linode_boot
- linode_clone
- linode_create
- linode_delete
- linode_update
- linode_deleteip
- linode_migrate
- linode_migrate_datacenter
- linode_migrate_datacenter_create
- linode_mutate
- linode_mutate_create
- linode_reboot
- linode_rebuild
- linode_resize
- linode_resize_create
- linode_shutdown
- linode_snapshot
- linode_config_create
- linode_config_delete
- linode_config_update
- lke_node_create
- longviewclient_create
- longviewclient_delete
- longviewclient_update
- managed_disabled
- managed_enabled
- managed_service_create
- managed_service_delete
- nodebalancer_create
- nodebalancer_delete
- nodebalancer_update
- nodebalancer_config_create
- nodebalancer_config_delete
- nodebalancer_config_update
- nodebalancer_node_create
- nodebalancer_node_delete
- nodebalancer_node_update
- oauth_client_create
- oauth_client_delete
- oauth_client_secret_reset
- oauth_client_update
- password_reset
- payment_method_add
- payment_submitted
- profile_update
- stackscript_create
- stackscript_delete
- stackscript_update
- stackscript_publicize
- stackscript_revise
- tag_create
- tag_delete
- tfa_disabled
- tfa_enabled
- ticket_attachment_upload
- ticket_create
- ticket_update
- token_create
- token_delete
- token_update
- user_create
- user_update
- user_delete
- user_ssh_key_add
- user_ssh_key_delete
- user_ssh_key_update
- vlan_attach
- vlan_detach
- volume_attach
- volume_clone
- volume_create
- volume_delete
- volume_update
- volume_detach
- volume_resize
readOnly: true
description: >
The action that caused this Event. New actions may be added in the future.
example: ticket_create
x-linode-cli-display: 3
x-linode-filterable: true
created:
type: string
readOnly: true
format: date-time
description: When this Event was created.
example: '2018-01-01T00:01:01'
x-linode-cli-display: 6
x-linode-filterable: true
duration:
type: number
readOnly: true
description: >
The total duration in seconds that it takes for the Event to complete.
example: 300.56
x-linode-cli-display: 7
entity:
type: object
readOnly: true
description: >
Detailed information about the Event's entity, including ID, type,
label, and URL used to access it.
properties:
id:
type: integer
description: |
The unique ID for an Event's entity.
Some Event entities do not have IDs associated with them, so they
will not be returned when filtering by ID. These Events include:
* `account`
* `profile`
Entities for some Events are assigned the ID of the Linode they correspond to.
When filtering by ID for these Events, use the corresponding Linode's ID.
These Events include:
* `disks`
* `backups`
Tag Events use a tag's name for the entity ID field. When filtering by ID
for tag Events, supply the name of the tag.
example: 11111
x-linode-filterable: true
label:
type: string
description: >
The current label of this object. The label may reflect changes
that occur with this Event.
example: Problem booting my Linode
x-linode-cli-display: 5
type:
type: string
enum:
- account
- backups
- community
- disks
- domain
- entity_transfer
- firewall
- image
- ipaddress
- linode
- longview
- managed_service
- nodebalancer
- oauth_client
- profile
- stackscript
- tag
- ticket
- token
- user
- user_ssh_key
- volume
readOnly: true
description: >
The type of entity that is being referenced by the Event.
example: ticket
x-linode-filterable: true
url:
type: string
description: >
The URL where you can access the object this Event is for. If
a relative URL, it is relative to the domain you retrieved the
Event from.
example: /v4/support/tickets/11111
secondary_entity:
type: object
readOnly: true
description: |
Detailed information about the Event's secondary entity, which provides additional information
for events such as, but not limited to, `linode_boot`, `linode_reboot`, `linode_create`, and `linode_clone` Event actions.
properties:
id:
type: string
description: >
The ID of the object that is the secondary entity.
example: linode/debian9
label:
type: string
description: >
The label of this object.
example: linode1234
type:
type: string
readOnly: true
description: >
The type of entity that is being referenced by the Event.
example: linode
url:
type: string
description: >
The URL where you can access the object this Event is for. If
a relative URL, it is relative to the domain you retrieved the
Event from.
example: /v4/linode/instances/1234
percent_complete:
type: integer
readOnly: true
description: >
A percentage estimating the amount of time remaining for an Event.
Returns `null` for notification events.
example: null
rate:
type: string
readOnly: true
description: >
The rate of completion of the Event. Only some Events will return
rate; for example, migration and resize Events.
example: null
read:
type: boolean
readOnly: true
description: If this Event has been read.
example: true
seen:
type: boolean
readOnly: true
description: If this Event has been seen.
example: true
status:
type: string
readOnly: true
description: The current status of this Event.
enum:
- failed
- finished
- notification
- scheduled
- started
x-linode-cli-display: 8
x-linode-cli-color:
failed: red
finished: green
started: yellow
default_: white
time_remaining:
type: string
readOnly: true
nullable: true
description: >
The estimated time remaining until the completion of this Event.
This value is only returned for some in-progress migration events.
For all other in-progress events, the `percent_complete` attribute
will indicate about how much more work is to be done.
example: null
username:
type: string
readOnly: true
description: >
The username of the User who caused the Event.
example: exampleUser
x-linode-cli-display: 2
message:
type: string
nullable: true
description: >
Provides additional information about the event. Additional
information may include, but is not limited to, a more detailed
representation of events which can help diagnose non-obvious failures.
example: None
x-linode-cli-display: 9
Firewall:
type: object
description: >
A resource that controls incoming and outgoing network traffic to a Linode service. Only one Firewall can be attached to a Linode at any given time.
[Create a Firewall Device](/docs/api/networking/#firewall-create)
to assign a Firewall to a Linode service. Currently, Firewalls can only be assigned to Linode instances.
properties:
id:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The Firewall's unique ID.
example: 123
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
description: |
The Firewall's label, for display purposes only.
Firewall labels have the following constraints:
* Must begin and end with an alphanumeric character.
* May only consist of alphanumeric characters, dashes (`-`), underscores (`_`) or periods (`.`).
* Cannot have two dashes (`--`), underscores (`__`) or periods (`..`) in a row.
* Must be between 3 and 32 characters.
* Must be unique.
example: firewall123
minLength: 3
maxLength: 32
pattern: '^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$'
x-linode-cli-display: 2
created:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
When this Firewall was created.
example: '2018-01-01T00:01:01'
x-linode-cli-display: 4
updated:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
When this Firewall was last updated.
example: '2018-01-02T00:01:01'
x-linode-cli-display: 5
status:
type: string
readOnly: true
description: >
The status of this Firewall.
* When a Firewall is first created its status is `enabled`.
* Use the [Update Firewall](/docs/api/networking/#firewall-update) endpoint to set a Firewall's status to `enabled` or `disabled`.
* Use the [Delete Firewall](/docs/api/networking/#firewall-delete) endpoint to delete a Firewall.
enum:
- enabled
- disabled
- deleted
example: enabled
x-linode-cli-display: 3
rules:
type: object
description: |
The inbound and outbound access rules to apply to the Firewall.
A Firewall may have up to 25 rules across its inbound and outbound rulesets.
properties:
inbound:
type: array
x-linode-cli-format: json
description: |
The inbound rules for the firewall, as a JSON array.
items:
$ref: '#/components/schemas/FirewallRuleConfig'
outbound:
type: array
x-linode-cli-format: json
description: |
The outbound rules for the firewall, as a JSON array.
items:
$ref: '#/components/schemas/FirewallRuleConfig'
inbound_policy:
type: string
enum:
- ACCEPT
- DROP
description: |
The default behavior for inbound traffic. This setting can be overridden by [updating](/docs/api/networking/#firewall-rules-update) the `inbound.action` property of the Firewall Rule.
example: DROP
outbound_policy:
type: string
enum:
- ACCEPT
- DROP
description: |
The default behavior for outbound traffic. This setting can be overridden by [updating](/docs/api/networking/#firewall-rules-update) the `outbound.action` property of the Firewall Rule.
example: DROP
tags:
x-linode-filterable: true
description: >
An array of tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
FirewallRuleConfig:
type: object
description: >
One of a Firewall's inbound or outbound access rules. The `ports` property
can be used to allow traffic on a comma-separated list of different ports.
properties:
protocol:
type: string
enum:
- TCP
- UDP
- ICMP
- IPENCAP
description: >
The type of network traffic to allow.
example: TCP
ports:
type: string
description: |
A string representing the port or ports on which traffic will be allowed:
- The string may be a single port, a range of ports, or a comma-separated list of single ports and port ranges. A space is permitted following each comma.
- A range of ports is inclusive of the start and end values for the range. The end value of the range must be greater than the start value.
- Ports must be within 1 and 65535, and may not contain any leading zeroes. For example, port "080" is not allowed.
- Ports may not be specified if a rule's protocol is `ICMP` or `IPENCAP`.
- At least one port must be specified if a rule's protocol is `TCP` or `UDP`.
- The ports string can have up to 15 *pieces*, where a single port is treated as one piece, and a port range is treated as two pieces. For example, the string "22-24, 80, 443" has four pieces.
example: '22-24, 80, 443'
addresses:
type: object
description: >
Allowed IPv4 or IPv6 addresses. A Rule can have up to 255 addresses
or networks listed across its IPv4 and IPv6 arrays. A network and a single IP
are treated as equivalent when accounting for this limit.
properties:
ipv4:
description: A list of IPv4 addresses or networks. Must be in IP/mask format.
type: array
items:
type: string
example:
- 192.0.2.0/24
ipv6:
description: A list of IPv6 addresses or networks. Must be in IP/mask format.
type: array
items:
type: string
example:
- 2001:DB8::/32
action:
type: string
enum:
- ACCEPT
- DROP
description: |
Controls whether traffic is accepted or dropped by this rule. Overrides the Firewall's `inbound_policy` if this is an inbound rule, or the `outbound_policy` if this is an outbound rule.
example: ACCEPT
label:
type: string
description: |
Used to identify this rule. For display purposes only.
example: firewallrule123
minLength: 3
maxLength: 32
description:
type: string
description: |
Used to describe this rule. For display purposes only.
example: 'An example firewall rule description.'
minLength: 1
maxLength: 100
FirewallDevices:
type: object
description: >
Associates a Firewall with a Linode service. A Firewall can be assigned
to a single Linode service at a time. Additional disabled Firewalls can be
assigned to a service, but they cannot be enabled if another active Firewall
is already assigned to the same service.
properties:
id:
x-linode-filterable: true
type: integer
description: >
The Device's unique ID
example: 123
x-linode-cli-display: 2
created:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
When this Device was created.
example: '2018-01-01T00:01:01'
x-linode-cli-display: 3
updated:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
When this Device was last updated.
example: '2018-01-02T00:01:01'
x-linode-cli-display: 4
entity:
type: object
readOnly: true
description: >
The Linode service that this Firewall has been applied to.
properties:
id:
description: The entity's ID
type: integer
example: 123
type:
description: The entity's type.
type: string
enum:
- linode
example: linode
label:
description: The entity's label.
type: string
readOnly: true
example: my-linode
url:
description: >
The URL you can use to access this entity.
type: string
format: url
readOnly: true
example: /v4/linode/instances/123
Grant:
type: object
description: >
Represents the level of access a restricted User has to a specific
resource on the Account.
properties:
id:
type: integer
description: >
The ID of the entity this grant applies to.
example: 123
permissions:
type: string
nullable: true
enum:
- read_only
- read_write
description: >
The level of access this User has to this entity. If null, this
User has no access.
example: read_only
label:
type: string
description: >
The current label of the entity this grant applies to, for display
purposes.
example: example-entity
readOnly: true
GrantsResponse:
type: object
description: >
A structure representing all grants a restricted User has on the
Account. Not available for unrestricted users, as they have access to
everything without grants. If retrieved from the `/profile/grants`
endpoint, entities to which a User has no access will be omitted.
properties:
global:
type: object
description: >
A structure containing the Account-level grants a User has.
properties:
add_linodes:
type: boolean
description: If true, this User may create Linodes.
example: true
add_longview:
type: boolean
description: If true, this User may create Longview clients and view the current plan.
example: true
longview_subscription:
type: boolean
description: If true, this User may manage the Account's Longview subscription.
example: true
account_access:
type: string
nullable: true
enum:
- read_only
- read_write
description: >
The level of access this User has to Account-level actions,
like billing information. A restricted User will never be able
to manage users.
example: read_only
cancel_account:
type: boolean
description: If true, this User may cancel the entire Account.
example: false
add_domains:
type: boolean
description: If true, this User may add Domains.
example: true
add_stackscripts:
type: boolean
description: If true, this User may add StackScripts.
example: true
add_nodebalancers:
type: boolean
description: If true, this User may add NodeBalancers.
example: true
add_images:
type: boolean
description: If true, this User may add Images.
example: true
add_volumes:
type: boolean
description: If true, this User may add Volumes.
example: true
add_firewalls:
type: boolean
description: If true, this User may add Firewalls.
example: true
add_databases:
type: boolean
description: if true, this User may add Managed Databases.
example: true
linode:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to Linodes on this Account.
There will be one entry per Linode on the Account.
domain:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to Domains on this Account.
There will be one entry per Domain on the Account.
nodebalancer:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to NodeBalancers on this
Account. There will be one entry per NodeBalancer on the Account.
image:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to Images on this Account.
There will be one entry per Image on the Account.
longview:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to Longview Clients on this
Account. There will be one entry per Longview Client on the
Account.
stackscript:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to StackScripts on this
Account. There will be one entry per StackScript on the Account.
volume:
type: array
items:
$ref: '#/components/schemas/Grant'
description: >
The grants this User has pertaining to Volumes on this Account.
There will be one entry per Volume on the Account.
Image:
type: object
description: Image object
properties:
id:
type: string
description: The unique ID of this Image.
example: linode/debian11
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
description: >
A short description of the Image.
example: Debian 11
x-linode-cli-display: 2
created:
type: string
format: date-time
description: When this Image was created.
example: '2021-08-14T22:44:02'
readOnly: true
updated:
type: string
format: date-time
description: When this Image was last updated.
example: '2021-08-14T22:44:02'
readOnly: true
created_by:
type: string
description: >
The name of the User who created this Image, or "linode" for
public Images.
example: linode
readOnly: true
deprecated:
x-linode-filterable: true
type: boolean
description: >
Whether or not this Image is deprecated. Will only be true for
deprecated public Images.
example: false
readOnly: true
description:
type: string
description: A detailed description of this Image.
example: Example Image description.
nullable: true
minLength: 1
maxLength: 65000
x-linode-cli-display: 4
x-linode-cli-color:
None: black
default_: white
is_public:
x-linode-filterable: true
description: True if the Image is a public distribution image. False if Image is private Account-specific Image.
type: boolean
example: true
readOnly: true
x-linode-cli-display: 5
size:
x-linode-filterable: true
type: integer
description: >
The minimum size this Image needs to deploy. Size is in MB.
example: 2500
readOnly: true
x-linode-cli-display: 6
type:
type: string
x-linode-filterable: true
description: |
How the Image was created.
"Manual" Images can be created at any time.
"Automatic" Images are created automatically from a deleted Linode.
enum:
- manual
- automatic
example: manual
readOnly: true
expiry:
type: string
format: date-time
nullable: true
description: >
Only Images created automatically from a deleted Linode (type=automatic) will expire.
example: null
readOnly: true
eol:
type: string
format: date-time
description: >
The date of the public Image's planned end of life. `None` for private Images.
example: '2026-07-01T04:00:00'
readOnly: true
vendor:
x-linode-filterable: true
type: string
description: >
The upstream distribution vendor. `None` for private Images.
example: Debian
readOnly: true
x-linode-cli-display: 3
x-linode-cli-color:
None: black
default_: white
status:
x-linode-cli-display: 7
type: string
readOnly: true
enum:
- creating
- pending_upload
- available
description: |
The current status of this Image. Only Images in an "available" status
can be deployed. Images in a "creating" status are being created from
a Linode Disk, and will become "available" shortly. Images in a
"pending_upload" status are waiting for data to be [uploaded](/docs/api/images/#image-upload),
and become "available" after the upload and processing are complete.
Invoice:
type: object
description: Account Invoice object
properties:
id:
type: integer
readOnly: true
description: The Invoice's unique ID.
example: 123
x-linode-cli-display: 1
date:
type: string
readOnly: true
format: date-time
description: When this Invoice was generated.
example: '2018-01-01T00:01:01'
x-linode-cli-display: 2
label:
type: string
readOnly: true
description: The Invoice's display label.
example: Invoice
x-linode-cli-display: 3
subtotal:
type: number
readOnly: true
description: The amount of the Invoice before taxes in US Dollars.
example: 120.25
x-linode-cli-display: 4
tax:
type: number
readOnly: true
description: The amount of tax levied on the Invoice in US Dollars.
example: 12.25
x-linode-cli-display: 5
tax_summary:
type: array
readOnly: true
description: The amount of tax broken down into subtotals by source.
items:
type: object
properties:
tax:
type: number
description: The amount of tax subtotal attributable to this source.
example: 12.25
name:
type: string
description: The source of this tax subtotal.
example: PA STATE TAX
total:
type: number
readOnly: true
description: The amount of the Invoice after taxes in US Dollars.
example: 132.50
x-linode-cli-display: 6
InvoiceItem:
type: object
description: An InvoiceItem object.
properties:
amount:
type: number
readOnly: true
description: The price, in US dollars, of the Invoice Item. Equal to the unit price multiplied by quantity.
example: 20.20
x-linode-cli-display: 4
tax:
type: number
readOnly: true
description: The amount of tax levied on this Item in US Dollars.
example: 1.25
x-linode-cli-display: 5
total:
type: number
readOnly: true
description: The price of this Item after taxes in US Dollars.
example: 21.45
x-linode-cli-display: 6
from:
type: string
readOnly: true
format: date-time
description: The date the Invoice Item started, based on month.
example: '2018-01-01T00:01:01'
x-linode-cli-display: 2
label:
type: string
readOnly: true
description: The Invoice Item's display label.
example: Linode 123
x-linode-cli-display: 1
quantity:
type: integer
readOnly: true
description: The quantity of this Item for the specified Invoice.
example: 4
to:
type: string
readOnly: true
format: date-time
description: The date the Invoice Item ended, based on month.
example: '2018-01-31T11:59:59'
x-linode-cli-display: 3
type:
type: string
readOnly: true
description: The type of service, ether `hourly` or `misc`.
enum:
- hourly
- misc
example: hourly
unit_price:
type: string
readOnly: true
description: The monthly service fee in US Dollars for this Item.
example: 5.05
IPAddress:
type: object
description: >
An IP address that exists in Linode's system, either IPv4 or IPv6.
properties:
address:
type: string
format: ip
description: >
The IP address.
example: 97.107.143.141
readOnly: true
x-linode-cli-display: 1
gateway:
type: string
nullable: true
format: ip
description: >
The default gateway for this address.
example: 97.107.143.1
readOnly: true
subnet_mask:
type: string
format: ip
description: >
The mask that separates host bits from network bits for this address.
example: 255.255.255.0
readOnly: true
prefix:
type: integer
description: >
The number of bits set in the subnet mask.
example: 24
readOnly: true
type:
type: string
enum:
- ipv4
- ipv6
- ipv6/pool
- ipv6/range
description: >
The type of address this is.
example: ipv4
readOnly: true
x-linode-cli-display: 2
public:
type: boolean
description: >
Whether this is a public or private IP address.
example: true
readOnly: true
x-linode-cli-display: 3
rdns:
type: string
description: >
The reverse DNS assigned to this address. For public IPv4 addresses,
this will be set to a default value provided by Linode if not
explicitly set.
x-linode-cli-display: 4
example: test.example.org
linode_id:
type: integer
description: >
The ID of the Linode this address currently belongs to. For IPv4
addresses, this is by default the Linode that this address was
assigned to on creation, and these addresses my be moved using the
[/networking/ipv4/assign](/docs/api/networking/#ips-to-linodes-assign)
endpoint. For SLAAC and link-local addresses, this value may not be changed.
example: 123
readOnly: true
x-linode-cli-display: 6
region:
type: string
description: >
The Region this IP address resides in.
example: us-east
readOnly: true
x-linode-filterable: true
x-linode-cli-display: 5
IPAddressesAssignRequest:
type: object
description: Request object for IP Addresses Assign (POST /networking/ips/assign).
required:
- region
- assignments
properties:
region:
type: string
description: >
The ID of the Region in which these assignments are to take
place. All IPs and Linodes must exist in this Region.
example: us-east
assignments:
type: array
description: >
The list of assignments to make. You must have read_write
access to all IPs being assigned and all Linodes being
assigned to in order for the assignments to succeed.
required:
- address
- linode_id
items:
type: object
properties:
address:
type: string
format: ipv4|ipv6/prefix_length
description: |
The IPv4 address or IPv6 range for this assignment.
* Must be an IPv4 address or an IPv6 range you can access in the Region specified.
* IPv6 ranges must include a prefix length of `/56` or `/64`, for example: `2001:db8:3c4d:15::/64`.
* Assignment of an IPv6 range to a Linode updates the route target of the range to the assigned Linode's SLAAC address.
* May be a public or private address.
example: 192.0.2.1
linode_id:
type: integer
description: >
The ID of the Linode to assign this address to. The IP's
previous Linode will lose this address, and must end up
with at least one public address and no more than one
private address once all assignments have been made.
example: 123
IPAddressesShareRequest:
type: object
description: A request object IP Addresses Share (POST /networking/ips/share)
required:
- linode_id
- ips
properties:
linode_id:
type: integer
description: >
The ID of the primary Linode that the addresses will be shared with.
example: 123
ips:
type: array
items:
type: string
format: ip
example:
- "192.0.2.1"
- "2001:db8:3c4d:15::"
description: |
A list of secondary Linode IPs to share with the primary Linode.
* Can include both IPv4 addresses and IPv6 ranges (omit /56 and /64 prefix lengths)
* Can include both private and public IPv4 addresses.
* You must have access to all of these addresses and they must be in the same Region as the primary Linode.
* Enter an empty array to remove all shared IP addresses.
IPAddressPrivate:
type: object
description: >
A private IPv4 address that exists in Linode's system.
properties:
address:
type: string
format: ip
description: >
The private IPv4 address.
example: 192.168.133.234
readOnly: true
x-linode-cli-display: 1
gateway:
type: string
format: ip
description: >
The default gateway for this address.
example: null
readOnly: true
subnet_mask:
type: string
format: ip
description: >
The mask that separates host bits from network bits for this address.
example: 255.255.128.0
readOnly: true
prefix:
type: integer
description: >
The number of bits set in the subnet mask.
example: 17
readOnly: true
type:
type: string
description: >
The type of address this is.
example: ipv4
readOnly: true
x-linode-cli-display: 2
public:
type: boolean
description: >
Whether this is a public or private IP address.
example: false
readOnly: true
x-linode-cli-display: 3
rdns:
type: string
description: >
The reverse DNS assigned to this address.
example: null
x-linode-cli-display: 4
linode_id:
type: integer
description: >
The ID of the Linode this address currently belongs to.
example: 123
readOnly: true
x-linode-cli-display: 6
region:
type: string
description: >
The Region this address resides in.
example: us-east
readOnly: true
x-linode-filterable: true
x-linode-cli-display: 5
IPAddressV6LinkLocal:
type: object
description: >
A link-local IPv6 address that exists in Linode's system,.
properties:
address:
type: string
format: ip
description: >
The IPv6 link-local address.
example: fe80::f03c:91ff:fe24:3a2f
readOnly: true
x-linode-cli-display: 1
gateway:
type: string
description: >
The default gateway for this address.
example: fe80::1
readOnly: true
subnet_mask:
type: string
format: ip
description: >
The subnet mask.
example: ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
readOnly: true
prefix:
type: integer
description: >
The network prefix.
example: 64
readOnly: true
type:
type: string
description: >
The type of address this is.
example: ipv6
readOnly: true
x-linode-cli-display: 2
public:
type: boolean
description: >
Whether this is a public or private IP address.
example: false
readOnly: true
x-linode-cli-display: 3
rdns:
type: string
description: >
The reverse DNS assigned to this address.
example: null
x-linode-cli-display: 4
linode_id:
type: integer
description: >
The ID of the Linode this address currently belongs to.
example: 123
readOnly: true
x-linode-cli-display: 6
region:
type: string
description: >
The Region this address resides in.
example: us-east
readOnly: true
x-linode-filterable: true
x-linode-cli-display: 5
IPAddressV6Slaac:
type: object
description: >
A SLAAC IPv6 address that exists in Linode's system.
properties:
address:
type: string
format: ip
description: >
The address.
example: 2600:3c03::f03c:91ff:fe24:3a2f
readOnly: true
x-linode-cli-display: 1
gateway:
type: string
description: >
The default gateway for this address.
example: fe80::1
readOnly: true
subnet_mask:
type: string
format: ip
description: >
The subnet mask.
example: ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
readOnly: true
prefix:
type: integer
description: >
The network prefix.
example: 64
readOnly: true
type:
type: string
description: >
The type of address this is.
example: ipv6
readOnly: true
x-linode-cli-display: 2
public:
type: boolean
description: >
Whether this is a public or private IP address.
example: true
readOnly: true
x-linode-cli-display: 3
rdns:
type: string
description: >
The reverse DNS assigned to this address.
example: null
x-linode-cli-display: 4
linode_id:
type: integer
description: >
The ID of the Linode this address currently belongs to.
example: 123
readOnly: true
x-linode-cli-display: 6
region:
type: string
description: >
The Region this address resides in.
example: us-east
readOnly: true
x-linode-filterable: true
x-linode-cli-display: 5
IPv6Pool:
type: object
description: >
An object representing an IPv6 pool.
properties:
range:
type: string
description: >
The IPv6 range of addresses in this pool.
example: '2600:3c01::2:5000:0'
readOnly: true
x-linode-cli-display: 1
prefix:
type: integer
description: >
The prefix length of the address, denoting how many addresses can be
assigned from this pool calculated as 2 <sup>128-prefix</sup>.
example: 124
x-linode-cli-display: 2
region:
type: string
description: >
The region for this pool of IPv6 addresses.
example: us-east
readOnly: true
x-linode-cli-display: 3
x-linode-filterable: true
route_target:
type: string
description: >
The last address in this block of IPv6 addresses.
example: '2600:3c01::2:5000:f'
nullable: true
IPv6Range:
type: object
description: >
An object representing an IPv6 range.
properties:
range:
type: string
description: >
The IPv6 range of addresses in this pool.
example: '2600:3c01::'
readOnly: true
x-linode-cli-display: 1
prefix:
type: integer
description: >
The prefix length of the address, denoting how many addresses can be
assigned from this range calculated as 2 <sup>128-prefix</sup>.
example: 64
x-linode-cli-display: 2
region:
type: string
description: >
The region for this range of IPv6 addresses.
example: us-east
readOnly: true
x-linode-cli-display: 3
route_target:
type: string
description: >
The last address in this block of IPv6 addresses.
example: '2600:3c01::ffff:ffff:ffff:ffff'
nullable: true
IPv6RangeBGP:
type: object
description: >
An object representing an IPv6 range.
properties:
range:
type: string
description: >
The IPv6 range of addresses in this pool.
example: '2600:3c01::'
readOnly: true
x-linode-cli-display: 1
prefix:
type: integer
description: >
The prefix length of the address, denoting how many addresses can be
assigned from this range calculated as 2 <sup>128-prefix</sup>.
example: 64
x-linode-cli-display: 2
region:
type: string
description: >
The region for this range of IPv6 addresses.
example: us-east
readOnly: true
x-linode-cli-display: 3
is_bgp:
type: boolean
description: >
Whether this IPv6 range is shared.
example: false
readOnly: true
linodes:
type: array
items:
type: integer
example:
- 123
description: >
A list of Linodes targeted by this IPv6 range. Includes Linodes with IP sharing.
readOnly: true
x-linode-cli-display: 4
Kernel:
type: object
description: Linux kernel object
properties:
id:
type: string
description: The unique ID of this Kernel.
example: linode/latest-64bit
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
description: The friendly name of this Kernel.
example: Latest 64 bit (4.15.7-x86_64-linode102)
readOnly: true
x-linode-cli-display: 2
version:
x-linode-filterable: true
type: string
description: Linux Kernel version.
example: 4.15.7
readOnly: true
x-linode-cli-display: 3
kvm:
x-linode-filterable: true
type: boolean
description: If this Kernel is suitable for KVM Linodes.
example: true
readOnly: true
xen:
x-linode-filterable: true
type: boolean
description: If this Kernel is suitable for Xen Linodes.
example: false
readOnly: true
architecture:
x-linode-filterable: true
type: string
description: The architecture of this Kernel.
enum:
- x86_64
- i386
example: x86_64
readOnly: true
x-linode-cli-display: 4
pvops:
x-linode-filterable: true
type: boolean
description: If this Kernel is suitable for paravirtualized operations.
example: false
readOnly: true
deprecated:
x-linode-filterable: true
type: boolean
description: If this Kernel is marked as deprecated, this field has a value of true;
otherwise, this field is false.
example: false
readOnly: true
built:
type: string
format: date-time
description: The date on which this Kernel was built.
example: '2018-01-01T00:01:01'
readOnly: true
Linode:
type: object
properties:
label:
x-linode-filterable: true
x-linode-cli-display: 2
type: string
description: |
The Linode's label is for display purposes only. If no label is provided for a Linode,
a default will be assigned.
Linode labels have the following constraints:
* Must begin and end with an alphanumeric character.
* May only consist of alphanumeric characters, dashes (`-`), underscores (`_`) or periods (`.`).
* Cannot have two dashes (`--`), underscores (`__`) or periods (`..`) in a row.
example: linode123
minLength: 3
maxLength: 64
pattern: '^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$'
region:
type: string
x-linode-filterable: true
readOnly: true
description: >
This is the [Region](/docs/api/regions/#regions-list) where the Linode was deployed. A Linode's region can only be changed by
initiating a [cross data center migration](/docs/api/linode-instances/#dc-migrationpending-host-migration-initiate).
x-linode-cli-display: 3
example: us-east
image:
x-linode-filterable: true
readOnly: true
nullable: true
allOf:
- $ref: '#/components/schemas/DiskRequest/properties/image'
x-linode-cli-display: 5
example: linode/debian10
type:
type: string
readOnly: true
description: >
This is the [Linode Type](/docs/api/linode-types/#types-list) that this
Linode was deployed with.
To change a Linode's Type, use
[POST /linode/instances/{linodeId}/resize](/docs/api/linode-instances/#linode-resize).
x-linode-cli-display: 4
example: g6-standard-1
group:
deprecated: true
type: string
x-linode-filterable: true
description: >
A deprecated property denoting a group label for this Linode.
example: "Linode-Group"
tags:
x-linode-filterable: true
description: >
An array of tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
id:
x-linode-filterable: true
type: integer
description: >
This Linode's ID which must be provided for all operations impacting this Linode.
example: 123
readOnly: true
x-linode-cli-display: 1
status:
type: string
description: >
A brief description of this Linode's current state. This field may change without
direct action from you. For example, when a Linode goes into maintenance mode
its status will display "stopped".
example: running
readOnly: true
enum:
- running
- offline
- booting
- rebooting
- shutting_down
- provisioning
- deleting
- migrating
- rebuilding
- cloning
- restoring
- stopped
x-linode-cli-display: 6
x-linode-cli-color:
running: green
offline: red
default_: yellow
hypervisor:
type: string
description: >
The virtualization software powering this Linode.
example: kvm
readOnly: true
enum:
- kvm
created:
type: string
format: date-time
description: When this Linode was created.
example: '2018-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Linode was last updated.
example: '2018-01-01T00:01:01'
readOnly: true
ipv4:
x-linode-filterable: true
type: array
format: ipv4
items:
type: string
example:
- 203.0.113.1
- 192.0.2.1
readOnly: true
description: |
This Linode's IPv4 Addresses. Each Linode is assigned a single public IPv4 address
upon creation, and may get a single private IPv4 address if needed. You may need to
[open a support ticket](/docs/api/support/#support-ticket-open)
to get additional IPv4 addresses.
IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes.
See the [/networking](/docs/api/networking/) endpoints for details.
x-linode-cli-display: 7
ipv6:
type: string
format: ipv6/128
nullable: true
description: >
This Linode's IPv6 SLAAC address. This address is specific to a Linode, and may not
be shared. If the Linode has not been assigned an IPv6 address, the return value will
be `null`.
example: 'c001:d00d::1337/128'
readOnly: true
specs:
type: object
description: Information about the resources available to this Linode.
readOnly: true
properties:
disk:
type: integer
description: >
The amount of storage space, in MB, this Linode has access to. A typical Linode
will divide this space between a primary disk with an `image` deployed to it, and
a swap disk, usually 512 MB. This is the default configuration created when
deploying a Linode with an `image` through
[POST /linode/instances](/docs/api/linode-instances/#linode-create).
While this configuration is suitable for 99% of use cases, if you need finer control over
your Linode's disks, see the
[/linode/instances/{linodeId}/disks](/docs/api/linode-instances/#disks-list)
endpoints.
example: 81920
readOnly: true
memory:
type: integer
description: >
The amount of RAM, in MB, this Linode has access to. Typically a Linode will
choose to boot with all of its available RAM, but this can be configured in a
Config profile, see the
[/linode/instances/{linodeId}/configs](/docs/api/linode-instances/#configuration-profiles-list)
endpoints and the LinodeConfig object for more information.
example: 4096
readOnly: true
vcpus:
type: integer
description: >
The number of vcpus this Linode has access to.
Typically a Linode will choose to
boot with all of its available vcpus, but this can be configured in a Config
Profile, see the
[/linode/instances/{linodeId}/configs](/docs/api/linode-instances/#configuration-profiles-list)
endpoints and the LinodeConfig object for more information.
example: 2
readOnly: true
transfer:
type: integer
description: The amount of network transfer this Linode is allotted each month.
example: 4000
readOnly: true
alerts:
type: object
properties:
cpu:
type: integer
description: |
The percentage of CPU usage required to trigger an alert.
If the average CPU usage over two hours exceeds this value, we'll send you an alert.
Your Linode's total CPU capacity is represented as 100%, multiplied by its number of
cores.
For example, a two core Linode's CPU capacity is represented as 200%. If you want
to be alerted at 90% of a two core Linode's CPU capacity, set the alert value to `180`.
The default value is 90% multiplied by the number of cores.
If the value is set to `0` (zero), the alert is disabled.
example: 180
network_in:
type: integer
description: >
The amount of incoming traffic, in Mbit/s, required to trigger an alert. If the
average incoming traffic over two hours exceeds this value, we'll send you an
alert. If this is set to `0` (zero), the alert is disabled.
example: 10
network_out:
type: integer
description: >
The amount of outbound traffic, in Mbit/s, required to trigger an alert. If the
average outbound traffic over two hours exceeds this value, we'll send you an
alert. If this is set to `0` (zero), the alert is disabled.
example: 10
transfer_quota:
type: integer
description: >
The percentage of network transfer that may be used before an alert is triggered.
When this value is exceeded, we'll alert you. If this is set to `0` (zero), the alert is
disabled.
example: 80
io:
type: integer
description: >
The amount of disk IO operation per second required to trigger an alert. If the
average disk IO over two hours exceeds this value, we'll send you an alert. If set
to `0` (zero), this alert is disabled.
example: 10000
backups:
type: object
description: >
Information about this Linode's backups status. For information about available
backups, see [/linode/instances/{linodeId}/backups](/docs/api/linode-instances/#backups-list).
properties:
enabled:
type: boolean
description: >
If this Linode has the Backup service enabled. To enable backups, see
[POST /linode/instances/{linodeId}/backups/enable](/docs/api/linode-instances/#backups-enable).
example: true
readOnly: true
schedule:
type: object
properties:
day:
type: string
nullable: true
description: |
The day of the week that your Linode's weekly Backup is taken.
If not set manually, a day will be chosen for you. Backups
are taken every day, but backups taken on this day are
preferred when selecting backups to retain for a longer period.
If not set manually, then when backups are initially enabled, this
may come back as `Scheduling` until the `day` is automatically selected.
example: Saturday
enum:
- Scheduling
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
window:
type: string
nullable: true
description: |
The window in which your backups will be taken, in UTC. A
backups window is a two-hour span of time in which the backup
may occur.
For example, `W10` indicates that your backups should be
taken between 10:00 and 12:00. If you do not choose a backup
window, one will be selected for you automatically.
If not set manually, when backups are initially enabled this
may come back as `Scheduling` until the `window` is automatically selected.
example: W22
enum:
- Scheduling
- W0
- W2
- W4
- W6
- W8
- W10
- W12
- W14
- W16
- W18
- W20
- W22
last_successful:
type: string
format: date-time
description: The last successful backup date. 'null' if there was no previous backup.
readOnly: true
example: '2018-01-01T00:01:01'
watchdog_enabled:
type: boolean
description: >
The watchdog, named Lassie, is a Shutdown Watchdog that monitors your Linode and will reboot it
if it powers off unexpectedly. It works by issuing a boot job when your
Linode powers off without a shutdown job being responsible.
To prevent a loop, Lassie will give up if there have been more than 5 boot
jobs issued within 15 minutes.
example: true
host_uuid:
type: string
format: uuid
description: The Linode's host machine, as a UUID.
readOnly: true
example: 3a3ddd59d9a78bb8de041391075df44de62bfec8
LinodeConfig:
type: object
properties:
id:
type: integer
description: The ID of this Config.
example: 23456
readOnly: true
x-linode-cli-display: 1
kernel:
type: string
description: A Kernel ID to boot a Linode with. Defaults to "linode/latest-64bit".
example: linode/latest-64bit
x-linode-cli-display: 3
comments:
type: string
nullable: true
description: Optional field for arbitrary User comments on this Config.
example: This is my main Config
memory_limit:
type: integer
description: >
Defaults to the total RAM of the Linode.
example: 2048
run_level:
type: string
description: >
Defines the state of your Linode after booting. Defaults to `default`.
enum:
- default
- single
- binbash
example: default
virt_mode:
type: string
description: >
Controls the virtualization mode. Defaults to `paravirt`.
* `paravirt` is suitable for most cases. Linodes running in paravirt mode
share some qualities with the host, ultimately making it run faster since
there is less transition between it and the host.
* `fullvirt` affords more customization, but is slower because 100% of the VM
is virtualized.
enum:
- paravirt
- fullvirt
example: paravirt
interfaces:
$ref: '#/components/schemas/LinodeConfigInterfaces'
helpers:
type: object
description: Helpers enabled when booting to this Linode Config.
properties:
updatedb_disabled:
type: boolean
description: Disables updatedb cron job to avoid disk thrashing.
example: true
distro:
type: boolean
description: Helps maintain correct inittab/upstart console device.
example: true
modules_dep:
type: boolean
description: Creates a modules dependency file for the Kernel you run.
example: true
network:
type: boolean
description: Automatically configures static networking.
example: true
devtmpfs_automount:
type: boolean
description: >
Populates the /dev directory early during boot without udev. Defaults to false.
example: false
label:
x-linode-filterable: true
type: string
description: >
The Config's label is for display purposes only.
example: My Config
minLength: 1
maxLength: 48
x-linode-cli-display: 2
devices:
$ref: '#/components/schemas/Devices'
root_device:
type: string
pattern: a-z, A-Z, 0-9, /, _, -
description: >
The root device to boot.
* If no value or an invalid value is provided, root device will default
to `/dev/sda`.
* If the device specified at the root device location is not mounted,
the Linode will not boot until a device is mounted.
example: /dev/sda
LinodeConfigInterface:
type: object
description: >
The Network Interface to apply to this Linode's configuration profile.
properties:
label:
type: string
minLength: 1
maxLength: 64
pattern: '/[a-z0-9-]+/'
x-linode-filterable: true
nullable: true
description: |
The name of this interface.
Required for `vlan` purpose interfaces. Must be an empty string or `null` for `public` purpose interfaces.
If the VLAN label is new, a VLAN is created. Up to 10 VLANs can be created in each data center region. To view your active VLANs, use the [VLANs List](/docs/api/networking/#vlans-list) endpoint.
May only consist of ASCII letters, numbers, and dashes (`-`).
Must be unique among the Linode's interfaces.
example: example-interface
ipam_address:
type: string
format: ip/netmask
nullable: true
description: |
This Network Interface's private IP address in Classless Inter-Domain Routing (CIDR) notation.
Only used for `vlan` purpose interfaces. Must be an empty string or `null` for `public` purpose interfaces.
The Linode is configured to use this address for the associated interface upon reboot if Network Helper is enabled. If Network Helper is disabled, the address can be enabled with [manual static IP configuration](/docs/guides/linux-static-ip-configuration/).
Must be unique among the Linode's interfaces.
example: '10.0.0.1/24'
purpose:
type: string
enum:
- public
- vlan
description: |
The type of interface.
* `public`
* Only one `public` interface per Linode can be defined.
* The Linode's default public IPv4 address is assigned to the `public` interface.
* A Linode must have a public interface in the first/eth0 position to be reachable via the public internet upon boot without additional system configuration. If no `public` interface is configured, the Linode is not directly reachable via the public internet. In this case, access can only be established via LISH or other Linodes connected to the same VLAN.
* `vlan`
* Configuring a `vlan` purpose interface attaches this Linode to the VLAN with the specified `label`.
* The Linode is configured to use the specified `ipam_address`, if any.
example: vlan
LinodeConfigInterfaces:
type: array
items:
$ref: '#/components/schemas/LinodeConfigInterface'
required:
- purpose
description: |
An array of Network Interfaces to add to this Linode's Configuration Profile.
Up to three interface objects can be entered in this array. The position in the array determines the interface to which the settings apply:
- First/0: eth0
- Second/1: eth1
- Third/2: eth2
When updating a Linode's interfaces, *each interface must be redefined*. An empty interfaces array results in a default public interface configuration only.
If no public interface is configured, public IP addresses are still assigned to the Linode but will not be usable without manual configuration.
**Note:** Changes to Linode interface configurations can be enabled by rebooting the Linode.
**Note:** Only Next Generation Network (NGN) data centers support VLANs. Use the Regions ([/regions](/docs/api/regions/)) endpoint to view the capabilities of data center regions.
If a VLAN is attached to your Linode and you attempt to migrate or clone it to a non-NGN data center,
the migration or cloning will not initiate. If a Linode cannot be migrated because of an incompatibility,
you will be prompted to select a different data center or contact support.
**Note:** See our guide on [Getting Started with VLANs](/docs/guides/getting-started-with-vlans/) to view additional [limitations](/docs/guides/getting-started-with-vlans/#limitations).
LinodeRequest:
type: object
description: Common properties for creating and rebuilding Linodes.
properties:
image:
$ref: '#/components/schemas/DiskRequest/properties/image'
root_pass:
$ref: '#/components/schemas/DiskRequest/properties/root_pass'
authorized_keys:
$ref: '#/components/schemas/DiskRequest/properties/authorized_keys'
authorized_users:
$ref: '#/components/schemas/DiskRequest/properties/authorized_users'
stackscript_id:
$ref: '#/components/schemas/DiskRequest/properties/stackscript_id'
stackscript_data:
$ref: '#/components/schemas/DiskRequest/properties/stackscript_data'
booted:
type: boolean
writeOnly: true
description: >
This field defaults to `true` if the Linode is created with an Image or from a
Backup.
If it is deployed from an Image or a Backup and you wish it to remain `offline`
after deployment, set this to `false`.
default: true
LinodeStats:
type: object
description: >
CPU, IO, IPv4, and IPv6 statistics. Graph data, if available,
is in "[timestamp, reading]" array format. Timestamp is a UNIX timestamp
in EST.
readOnly: true
properties:
cpu:
type: array
description: >
Percentage of CPU used.
items:
type: array
items:
type: number
example:
- 1521483600000
- 0.42
io:
type: object
description: Input/Output statistics.
properties:
io:
type: array
description: Block/s written.
items:
type: array
items:
type: number
example:
- 1521484800000
- 0.19
swap:
type: array
description: Block/s written.
items:
type: array
items:
type: number
example:
- 1521484800000
- 0
netv4:
type: object
description: IPv4 statistics.
properties:
in:
type: array
description: Input stats for IPv4, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 2004.36
out:
type: array
description: Output stats for IPv4, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 3928.91
private_in:
type: array
description: Private IPv4 input statistics, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 0
private_out:
type: array
description: Private IPv4 output statistics, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 5.6
netv6:
type: object
description: IPv6 statistics.
properties:
in:
type: array
description: Input stats for IPv6, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 0
out:
type: array
description: Output stats for IPv6, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 0
private_in:
type: array
description: Private IPv6 input statistics, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 195.18
private_out:
type: array
description: Private IPv6 output statistics, measured in bits/s (bits/second).
items:
type: array
items:
type: number
example:
- 1521484800000
- 5.6
title:
type: string
description: The title for this data set.
example: linode.com - my-linode (linode123456) - day (5 min avg)
LinodeType:
type: object
description: >
Returns collection of Linode types, including pricing and specifications
for each type. These are used when
[creating](/docs/api/linode-instances/#linode-create)
or [resizing](/docs/api/linode-instances/#linode-resize)
Linodes.
properties:
id:
readOnly: true
type: string
description: The ID representing the Linode Type.
example: g6-standard-2
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
readOnly: true
description: >
The Linode Type's label is for display purposes only.
example: Linode 4GB
x-linode-cli-display: 2
disk:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The Disk size, in MB, of the Linode Type.
example: 81920
x-linode-cli-display: 4
class:
x-linode-filterable: true
type: string
readOnly: true
description: >
The class of the Linode Type. We currently offer five classes of Linodes:
* nanode - Nanode instances are good for low-duty workloads,
where performance isn't critical. **Note:** As of June 16th, 2020, Nanodes became
1 GB Linodes in the Cloud Manager, however, the API, the CLI, and billing will
continue to refer to these instances as Nanodes.
* standard - Standard Shared instances are good for medium-duty workloads and
are a good mix of performance, resources, and price. **Note:** As of June 16th, 2020,
Standard Linodes in the Cloud Manager became Shared Linodes, however, the API, the CLI, and
billing will continue to refer to these instances as Standard Linodes.
* dedicated - Dedicated CPU instances are good for full-duty workloads
where consistent performance is important.
* gpu - Linodes with dedicated NVIDIA Quadro ® RTX 6000 GPUs accelerate highly
specialized applications such as machine learning, AI, and video transcoding.
* highmem - High Memory instances favor RAM over other resources, and can be
good for memory hungry use cases like caching and in-memory databases.
All High Memory plans contain dedicated CPU cores.
enum:
- nanode
- standard
- dedicated
- gpu
- highmem
example: standard
x-linode-cli-display: 3
price:
type: object
readOnly: true
description: >
Cost in US dollars, broken down into hourly and monthly charges.
properties:
hourly:
type: integer
description: Cost (in US dollars) per hour.
example: 0.03
x-linode-cli-display: 9
monthly:
type: integer
description: Cost (in US dollars) per month.
example: 20
x-linode-cli-display: 10
addons:
type: object
readOnly: true
description: >
A list of optional add-on services for Linodes and their associated
costs.
properties:
backups:
type: object
readOnly: true
description: >
Information about the optional Backup service offered for Linodes.
properties:
price:
type: object
description: Cost of enabling Backups for this Linode Type.
properties:
hourly:
type: integer
description: >
The cost (in US dollars) per hour to add Backups service.
example: 0.008
monthly:
type: integer
description: >
The cost (in US dollars) per month to add Backups service.
example: 5
network_out:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The Mbits outbound bandwidth allocation.
example: 1000
x-linode-cli-display: 7
memory:
x-linode-filterable: true
type: integer
readOnly: true
description: >
Amount of RAM included in this Linode Type.
example: 4096
x-linode-cli-display: 5
successor:
type: string
readOnly: true
nullable: true
description: >
The Linode Type that a [mutate](/docs/api/linode-instances/#linode-upgrade)
will upgrade to for a Linode of this type. If "null", a Linode of this type
may not mutate.
example: null
transfer:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The monthly outbound transfer amount, in MB.
example: 4000
x-linode-cli-display: 8
vcpus:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The number of VCPU cores this Linode Type offers.
example: 2
x-linode-cli-display: 6
gpus:
x-linode-filterable: true
type: integer
readOnly: true
description: >
The number of GPUs this Linode Type offers.
example: 0
x-linode-cli-display: 11
LKECluster:
type: object
description: A Kubernetes cluster.
properties:
id:
type: integer
description: This Kubernetes cluster's unique ID.
readOnly: true
x-linode-cli-display: 1
example: 1234
created:
type: string
format: date-time
description: When this Kubernetes cluster was created.
example: "2019-09-12T21:25:30Z"
readOnly: true
updated:
type: string
format: date-time
description: When this Kubernetes cluster was updated.
example: "2019-09-13T21:24:16Z"
readOnly: true
label:
type: string
description: >
This Kubernetes cluster's unique label for display purposes only.
Labels have the following constraints:
* UTF-8 characters will be returned by the API using escape
sequences of their Unicode code points. For example, the
Japanese character *か* is 3 bytes in UTF-8 (`0xE382AB`). Its
Unicode code point is 2 bytes (`0x30AB`). APIv4 supports this
character and the API will return it as the escape sequence
using six 1 byte characters which represent 2 bytes of Unicode
code point (`"\u30ab"`).
* 4 byte UTF-8 characters are not supported.
* If the label is entirely composed of UTF-8 characters, the API
response will return the code points using up to 193 1 byte
characters.
minLength: 1
maxLength: 32
x-linode-filterable: true
x-linode-cli-display: 2
example: lkecluster12345
region:
type: string
description: This Kubernetes cluster's location.
x-linode-cli-display: 3
example: us-central
k8s_version:
type: string
description: >
The desired Kubernetes version for this Kubernetes cluster in the format of <major>.<minor>,
and the latest supported patch version will be deployed.
example: "1.23"
control_plane:
type: object
description: >
Defines settings for the Kubernetes Control Plane. Allows for the enabling of High Availability (HA) for Control Plane Components. Enabling High Avaialability for LKE is an **irreversible** change.
properties:
high_availability:
type: boolean
description: >
Defines whether High Availability is enabled for the Control Plane Components of the cluster. Defaults to `false`.
example: true
tags:
x-linode-filterable: true
type: array
description: >
An array of tags applied to the Kubernetes cluster.
Tags are for organizational purposes only.
items:
type: string
example:
- ecomm
- blogs
LKENodePoolRequestBody:
type: object
description: >
Specifies a collection of Linodes which will be members of a Kubernetes
cluster.
properties:
autoscaler:
type: object
description: |
When enabled, the number of nodes autoscales within the defined minimum and maximum values.
When making a request, `max` and `min` require each other.
properties:
enabled:
type: boolean
description: Whether autoscaling is enabled for this Node Pool. Defaults to `false`.
example: true
max:
type: integer
minimum: 1
maximum: 100
description: |
The maximum number of nodes to autoscale to. Defaults to the Node Pool's `count`. Defaults to the value provided by the `count` field.
example: 12
min:
type: integer
minimum: 1
maximum: 100
description: The minimum number of nodes to autoscale to. Defaults to the Node Pool's `count`.
example: 3
type:
$ref: '#/components/schemas/LKENodePool/properties/type'
count:
$ref: '#/components/schemas/LKENodePool/properties/count'
disks:
type: array
x-linode-cli-format: json
description: |
**Note**: This field should be omitted except for special use cases. The disks specified here are
partitions in *addition* to the primary partition and reduce the size of the primary partition,
which can lead to stability problems for the Node.
This Node Pool's custom disk layout. Each item in this array will create a new disk
partition for each node in this Node Pool.
* The custom disk layout is applied to each node in this Node Pool.
* The maximum number of custom disk partitions that can be configured is 7.
* Once the requested disk paritions are allocated, the remaining disk space is allocated to the node's boot disk.
* A Node Pool's custom disk layout is immutable over the lifetime of the Node Pool.
items:
$ref: '#/components/schemas/LKENodePool/properties/disks/items'
tags:
$ref: '#/components/schemas/LKENodePool/properties/tags'
LKENodePool:
type: object
description: >
The set of Node Pools which are members of the Kubernetes cluster.
Node Pools consist of a Linode type, the number of Linodes to
deploy of that type, and additional status information.
properties:
autoscaler:
type: object
description: |
When enabled, the number of nodes autoscales within the defined minimum and maximum values.
properties:
enabled:
type: boolean
description: Whether autoscaling is enabled for this Node Pool. Defaults to `false`.
example: true
max:
type: integer
minimum: 1
maximum: 100
description: The maximum number of nodes to autoscale to. Defaults to the Node Pool's `count`.
example: 12
min:
type: integer
minimum: 1
maximum: 100
description: The minimum number of nodes to autoscale to. Defaults to the Node Pool's `count`.
example: 3
type:
type: string
description: The Linode Type for all of the nodes in the Node Pool.
example: g6-standard-4
count:
type: integer
description: The number of nodes in the Node Pool.
minimum: 1
maximum: 100
example: 6
disks:
type: array
x-linode-cli-format: json
description: |
This Node Pool's custom disk layout.
items:
type: object
description: >
The values to assign to each partition in this Node Pool's custom disk layout.
properties:
size:
description: >
The size of this custom disk partition in MB.
* The size of this disk partition must not exceed the capacity of the node's plan type.
type: integer
example: 1024
type:
description: >
This custom disk partition's filesystem type.
type: string
enum:
- raw
- ext4
example: ext-4
id:
type: integer
description: >
This Node Pool's unique ID.
x-linode-filterable: true
example: 456
nodes:
type: array
description: >
Status information for the Nodes which are members of this Node
Pool. If a Linode has not been provisioned for a given Node slot,
the instance_id will be returned as null.
items:
$ref: '#/components/schemas/LKENodeStatus'
tags:
x-linode-filterable: true
description: >
An array of tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
LKENodeStatus:
type: object
description: >
Status information for a Node which is a member of a Kubernetes
cluster.
readOnly: true
properties:
id:
type: string
description: >
The Node's ID.
example: "123456"
instance_id:
type: string
description: >
The Linode's ID. When no Linode is currently provisioned for this
Node, this will be null.
example: 123458
status:
type: string
description: >
The Node's status as it pertains to being a Kubernetes node.
enum:
- ready
- not_ready
example: ready
LKEVersion:
type: object
description: >
LKE versions
readOnly: true
properties:
id:
type: string
description: >
A Kubernetes version number available for deployment
to a Kubernetes cluster in the format of <major>.<minor>,
and the latest supported patch version.
example: "1.23"
LongviewClient:
type: object
description: >
A LongviewClient is a single monitor set up to track statistics about
one of your servers.
properties:
id:
type: integer
description: >
This Client's unique ID.
example: 789
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
minLength: 3
maxLength: 32
pattern: '[a-zA-Z0-9-_]{3,32}'
description: >
This Client's unique label. This is for display purposes only.
example: client789
x-linode-cli-display: 2
api_key:
type: string
description: |
The API key for this Client, used when configuring the Longview
Client application on your Linode.
Returns as `[REDACTED]` if you do not have read-write access to this client.
example: BD1B4B54-D752-A76D-5A9BD8A17F39DB61
readOnly: true
install_code:
type: string
description: |
The install code for this Client, used when configuring the Longview
Client application on your Linode.
Returns as `[REDACTED]` if you do not have read-write access to this client.
example: BD1B5605-BF5E-D385-BA07AD518BE7F321
readOnly: true
x-linode-cli-display: 4
apps:
type: object
description: >
The apps this Client is monitoring on your Linode. This is configured
when you install the Longview Client application, and is present here
for information purposes only.
readOnly: true
properties:
apache:
type: boolean
description: >
If True, the Apache Longview Client module is monitoring Apache on
your server.
example: true
readOnly: true
nginx:
type: boolean
description: >
If True, the Nginx Longview Client module is monitoring Nginx on
your server.
example: false
readOnly: true
mysql:
type: boolean
description: >
If True, the MySQL Longview Client modules is monitoring MySQL on
your server.
example: true
readOnly: true
created:
type: string
format: date-time
description: >
When this Longview Client was created.
example: 2018-01-01T00:01:01
readOnly: true
x-linode-cli-display: 3
updated:
type: string
format: date-time
description: >
When this Longview Client was last updated.
example: 2018-01-01T00:01:01
readOnly: true
Login:
type: object
description: >
An object representing a previous successful login for a User.
properties:
id:
type: integer
description: >
The unique ID of this login object.
example: 1234
readOnly: true
x-linode-cli-display: 1
datetime:
type: string
format: date-time
description: >
When the login was initiated.
example: '2018-01-01T00:01:01'
readOnly: true
x-linode-cli-display: 2
ip:
type: string
format: ip
description: >
The remote IP address that requested the login.
example: 192.0.2.0
readOnly: true
x-linode-cli-display: 3
username:
type: string
description: >
The username of the User that was logged into.
example: example_user
readOnly: true
x-linode-cli-display: 4
restricted:
type: boolean
description: >
True if the User that was logged into was a restricted User, false otherwise.
example: true
readOnly: true
x-linode-cli-display: 5
LongviewSubscription:
type: object
description: >
A Longview Subscription represents a tier of Longview service you
can subscribe to.
properties:
id:
type: string
enum: ['longview-3', 'longview-10', 'longview-40', 'longview-100']
description: >
The unique ID of this Subscription tier.
example: longview-10
readOnly: true
x-linode-cli-display: 1
price:
type: object
description: >
Pricing information about this Subscription tier.
readOnly: true
x-linode-cli-display: 4
properties:
hourly:
type: number
description: >
The hourly price, in US dollars, for this Subscription tier.
example: 0.06
readOnly: true
monthly:
type: number
description: >
The maximum monthly price in US Dollars for this Subscription tier.
You will never be charged more than this amount per
month for this subscription.
example: 40
readOnly: true
label:
type: string
description: >
A display name for this Subscription tier.
example: Longview Pro 10 pack
readOnly: true
x-linode-cli-display: 2
clients_included:
type: integer
description: >
The number of Longview Clients that may be created with this Subscription tier.
example: 10
readOnly: true
x-linode-cli-display: 3
LongviewPlan:
type: object
description: >
Longview Plan object.
properties:
longview_subscription:
type: string
enum: ['longview-3', 'longview-10', 'longview-40', 'longview-100']
nullable: True
description: >
The subscription ID for a particular Longview plan. A value of `null` corresponds to Longview Free.
You can send a request to the [List Longview Subscriptions](/docs/api/longview/#longview-subscriptions-list)
endpoint to receive the details of each plan.
example: longview-10
x-linode-cli-display: 1
Maintenance:
type: object
description: >
Information about maintenance affecting an entity.
properties:
type:
x-linode-filterable: true
type: string
enum:
- reboot
- cold_migration
- live_migration
description: >
The type of maintenance.
example: reboot
status:
x-linode-filterable: true
type: string
enum:
- pending
- started
description: >
The maintenance status.
example: started
reason:
type: string
description: >
The reason maintenance is being performed.
example: This maintenance will allow us to update the BIOS on the host's motherboard.
when:
x-linode-filterable: true
type: string
description: |
When the maintenance will begin.
[Filterable](/docs/api/#filtering-and-sorting) with the following parameters:
* A single value in date-time string format ("%Y-%m-%dT%H:%M:%S"), which returns only matches to that value.
* A dictionary containing pairs of inequality operator string keys ("+or", "+gt", "+gte", "+lt", "+lte",
or "+neq") and single date-time string format values ("%Y-%m-%dT%H:%M:%S"). "+or" accepts an array of values that
may consist of single date-time strings or dictionaries of inequality operator pairs.
format: date-time
example: 2020-07-09T00:01:01
entity:
type: object
description: >
The entity being affected by maintenance.
properties:
label:
type: string
description: >
The label of the entity being affected by maintenance.
example: demo-linode
id:
type: number
description: >
The id of the entity being affected by maintenance.
example: 1234
type:
type: string
description: >
The type of entity.
example: Linode
url:
type: string
description: >
The API endpoint prefix to use in combination with the entity id to find specific information about the entity.
example: https://api.linode.com/v4/linode/instances/{linodeId}
ManagedContact:
type: object
description: >
Information about someone Linode's special forces may contact
in case an issue is detected with a manager service.
properties:
id:
type: integer
description: >
This Contact's unique ID.
example: 567
readOnly: true
x-linode-cli-display: 1
name:
type: string
minLength: 2
maxLength: 64
pattern: '[a-zA-Z0-9-_ ]{2,64}'
description: >
The name of this Contact.
example: John Doe
x-linode-cli-display: 2
email:
type: string
format: email
description: >
The address to email this Contact to alert them of issues.
example: john.doe@example.org
x-linode-cli-display: 3
phone:
type: object
description: >
Information about how to reach this Contact by phone.
x-linode-cli-display: 4
properties:
primary:
type: string
nullable: true
format: phone
description: >
This Contact's primary phone number.
example: 123-456-7890
secondary:
type: string
nullable: true
format: phone
description: >
This Contact's secondary phone number.
example: null
group:
x-linode-filterable: true
nullable: true
type: string
minLength: 2
maxLength: 50
description: >
A grouping for this Contact. This is for display purposes only.
example: on-call
x-linode-cli-display: 5
updated:
type: string
format: date-time
description: >
When this Contact was last updated.
example: '2018-01-01T00:01:01'
readOnly: true
ManagedCredential:
type: object
description: >
A securely-stored Credential that allows Linode's special forces
to access a Managed server to respond to Issues.
properties:
id:
type: integer
description: >
This Credential's unique ID.
example: 9991
readOnly: true
x-linode-cli-display: 1
label:
type: string
minLength: 2
maxLength: 75
pattern: '[a-zA-Z0-9-_ \.]{2,75}'
description: >
The unique label for this Credential. This is for display purposes
only.
example: prod-password-1
x-linode-cli-display: 2
last_decrypted:
type: string
format: date-time
description: >
The date this Credential was last decrypted by a member of Linode
special forces.
readOnly: true
example: "2018-01-01T00:01:01"
x-linode-cli-display: 3
ManagedIssue:
type: object
description: >
An Issue that was detected with a service Linode is managing.
properties:
id:
type: integer
description: >
This Issue's unique ID.
example: 823
readOnly: true
x-linode-cli-display: 1
created:
type: string
format: date-time
description: >
When this Issue was created. Issues are created in response to issues
detected with Managed Services, so this is also when the Issue was
detected.
example: '2018-01-01T00:01:01'
readOnly: true
x-linode-cli-display: 2
services:
type: array
items:
type: integer
example: 654
description: >
An array of Managed Service IDs that were affected by this Issue.
readOnly: true
x-linode-cli-display: 3
entity:
type: object
description: >
The ticket this Managed Issue opened.
readOnly: true
x-linode-cli-display: 4
properties:
id:
type: integer
description: >
This ticket's ID
example: 98765
readOnly: true
type:
type: string
enum:
- ticket
description: >
The type of entity this is. In this case, it is always a Ticket.
example: ticket
readOnly: true
label:
type: string
description: >
The summary for this Ticket.
example: Managed Issue opened!
readOnly: true
url:
type: string
format: url
description: >
The relative URL where you can access this Ticket.
example: /support/tickets/98765
readOnly: true
ManagedLinodeSettings:
type: object
description: >
Settings for a specific Linode related to Managed Services. There is
one ManagedLinodeSettings object for each Linode on your Account.
properties:
id:
type: integer
description: >
The ID of the Linode these Settings are for.
example: 123
readOnly: true
x-linode-cli-display: 1
label:
type: string
description: >
The label of the Linode these Settings are for.
example: linode123
readOnly: true
x-linode-cli-display: 2
group:
deprecated: true
type: string
description: >
The group of the Linode these Settings are for. This is for display
purposes only.
example: linodes
readOnly: true
x-linode-cli-display: 3
ssh:
type: object
description: >
The SSH settings for this Linode.
x-linode-cli-display: 4
properties:
access:
type: boolean
description: >
If true, Linode special forces may access this Linode over
ssh to respond to Issues.
example: true
default: true
user:
type: string
minLength: 0
maxLength: 32
description: |
The specific user, if any, Linode's special forces should use when accessing this
Linode to respond to an issue.
The default `null` value corresponds to the root user.
example: linode
default: null
nullable: true
ip:
type: string
format: ip
description: |
The IP Linode special forces should use to access this Linode
when responding to an Issue.
By default, any of a Linode's IP addresses can be used for incident response access.
example: "12.34.56.78"
default: any
port:
type: integer
minimum: 1
maximum: 65535
description: |
The port Linode special forces should use to access this Linode
over ssh to respond to an Issue.
The default `null` value corresponds to port 22.
example: 22
nullable: true
default: null
ManagedService:
type: object
description: >
A service that Linode is monitoring as part of your Managed services.
If issues are detected with this service, a ManagedIssue will be opened
and, optionally, Linode special forces will attempt to resolve the Issue.
properties:
id:
type: integer
description: >
This Service's unique ID.
example: 9944
readOnly: true
x-linode-cli-display: 1
status:
type: string
enum:
- disabled
- pending
- ok
- problem
description: >
The current status of this Service.
example: ok
readOnly: true
x-linode-cli-display: 2
x-linode-cli-color:
ok: green
disabled: red
default_: yellow
service_type:
type: string
enum:
- url
- tcp
description: >
How this Service is monitored.
example: url
x-linode-cli-display: 3
label:
type: string
minLength: 3
maxLength: 64
pattern: '[a-zA-Z0-9-_ \.]{3,64}'
description: >
The label for this Service. This is for display purposes only.
example: prod-1
x-linode-cli-display: 4
address:
type: string
format: url
minLength: 3
maxLength: 100
description: >
The URL at which this Service is monitored.
URL parameters such as `?no-cache=1` are preserved.
URL fragments/anchors such as `#monitor` are **not** preserved.
example: https://example.org
x-linode-cli-display: 5
timeout:
type: integer
minimum: 1
maximum: 255
description: >
How long to wait, in seconds, for a response before considering the
Service to be down.
example: 30
body:
type: string
nullable: true
minLength: 0
maxLength: 100
description: >
What to expect to find in the response body for the Service to be
considered up.
example: it worked
consultation_group:
type: string
minLength: 0
maxLength: 50
description: >
The group of ManagedContacts who should be notified or consulted
with when an Issue is detected.
example: on-call
x-linode-cli-display: 6
notes:
type: string
nullable: true
description: >
Any information relevant to the Service that Linode special forces
should know when attempting to resolve Issues.
example: The service name is my-cool-application
region:
type: string
description: >
The Region in which this Service is located. This is required if
address is a private IP, and may not be set otherwise.
example: null
credentials:
type: array
items:
type: integer
example: 9991
description: >
An array of ManagedCredential IDs that should be used when attempting to
resolve issues with this Service.
created:
type: string
format: date-time
description: When this Managed Service was created.
example: '2018-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Managed Service was last updated.
example: '2018-03-01T00:01:01'
readOnly: true
NodeBalancer:
type: object
description: >
Linode's load balancing solution. Can handle multiple ports, SSL termination,
and any number of backends. NodeBalancer ports are configured with
NodeBalancer Configs, and each config is given one or more NodeBalancer Node that
accepts traffic. The traffic should be routed to the NodeBalancer's ip address,
the NodeBalancer will handle routing individual requests to backends.
properties:
id:
type: integer
description: >
This NodeBalancer's unique ID.
example: 12345
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
minLength: 3
maxLength: 32
pattern: '[a-zA-Z0-9-_]{3,32}'
description: >
This NodeBalancer's label. These must be unique on your Account.
example: balancer12345
x-linode-cli-display: 2
region:
x-linode-filterable: true
type: string
description: >
The Region where this NodeBalancer is located. NodeBalancers only
support backends in the same Region.
example: us-east
readOnly: true
x-linode-cli-display: 3
hostname:
type: string
description: >
This NodeBalancer's hostname, beginning with its IP address and ending with _.ip.linodeusercontent.com_.
example: 192.0.2.1.ip.linodeusercontent.com
readOnly: true
x-linode-cli-display: 4
ipv4:
x-linode-filterable: true
type: string
format: ip
description: >
This NodeBalancer's public IPv4 address.
example: 12.34.56.78
readOnly: true
x-linode-cli-display: 5
ipv6:
type: string
nullable: true
format: ip
description: >
This NodeBalancer's public IPv6 address.
example: null
readOnly: true
x-linode-cli-display: 6
created:
type: string
format: date-time
description: >
When this NodeBalancer was created.
example: 2018-01-01T00:01:01
readOnly: true
updated:
type: string
format: date-time
description: >
When this NodeBalancer was last updated.
example: 2018-03-01T00:01:01
readOnly: true
client_conn_throttle:
type: integer
minimum: 0
maximum: 20
description: >
Throttle connections per second. Set to 0 (zero) to disable throttling.
example: 0
x-linode-cli-display: 6
transfer:
type: object
description: >
Information about the amount of transfer this NodeBalancer has had
so far this month.
properties:
total:
type: number
nullable: true
description: >
The total transfer, in MB, used by this NodeBalancer this month.
example: 32.46078109741211
readOnly: true
out:
type: number
nullable: true
description: >
The total inbound transfer, in MB, used for this NodeBalancer
this month.
example: 3.5487728118896484
readOnly: true
in:
type: number
nullable: true
description: >
The total outbound transfer, in MB, used for this NodeBalancer
this month.
example: 28.91200828552246
readOnly: true
tags:
x-linode-filterable: true
description: >
An array of Tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
NodeBalancerConfig:
type: object
description: >
A NodeBalancer config represents the configuration of this NodeBalancer
on a single port. For example, a NodeBalancer Config on port 80 would
typically represent how this NodeBalancer response to HTTP requests.
NodeBalancer configs have a list of backends, called "nodes," that they
forward requests between based on their configuration.
properties:
id:
type: integer
description: This config's unique ID
example: 4567
readOnly: true
x-linode-cli-display: 1
port:
type: integer
minimum: 1
maximum: 65535
default: 80
description: >
The port this Config is for. These values must be unique across configs
on a single NodeBalancer (you can't have two configs for port 80, for
example). While some ports imply some protocols, no enforcement is done
and you may configure your NodeBalancer however is useful to you. For
example, while port 443 is generally used for HTTPS, you do not need
SSL configured to have a NodeBalancer listening on port 443.
example: 80
x-linode-cli-display: 2
protocol:
type: string
enum:
- http
- https
- tcp
default: http
description: |
The protocol this port is configured to serve.
* The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`.
* The `https` protocol is mutually required with `ssl_cert` and `ssl_key`.
Review our guide on [Available Protocols](/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features.
example: http
x-linode-cli-display: 3
algorithm:
type: string
enum:
- roundrobin
- leastconn
- source
default: roundrobin
description: >
What algorithm this NodeBalancer should use for routing traffic to backends.
example: roundrobin
x-linode-cli-display: 4
stickiness:
type: string
enum:
- none
- table
- http_cookie
default: none
description: >
Controls how session stickiness is handled on this port.
* If set to `none` connections will always be assigned a backend based on the algorithm configured.
* If set to `table` sessions from the same remote address will be routed to the same
backend.
* For HTTP or HTTPS clients, `http_cookie` allows sessions to be
routed to the same backend based on a cookie set by the NodeBalancer.
example: http_cookie
x-linode-cli-display: 5
check:
type: string
enum:
- none
- connection
- http
- http_body
default: none
description: >
The type of check to perform against backends to ensure they are serving
requests. This is used to determine if backends are up or down.
* If `none` no check is performed.
* `connection` requires only a connection to the backend to succeed.
* `http` and `http_body` rely on the backend serving HTTP, and that
the response returned matches what is expected.
example: http_body
check_interval:
type: integer
description: |
How often, in seconds, to check that backends are up and serving requests.
Must be greater than `check_timeout`.
example: 90
default: 31
check_timeout:
type: integer
minimum: 1
maximum: 30
default: 30
description: |
How long, in seconds, to wait for a check attempt before considering it failed.
Must be less than `check_interval`.
example: 10
check_attempts:
type: integer
minimum: 1
maximum: 30
default: 3
description: >
How many times to attempt a check before considering a backend to be down.
example: 3
check_path:
type: string
pattern: ^[a-zA-Z0-9\/\-%?&=.]*$
description: >
The URL path to check on each backend. If the backend does not respond
to this request it is considered to be down.
example: /test
check_body:
type: string
description: >
This value must be present in the response body of the check in order for
it to pass. If this value is not present in the response body of a check
request, the backend is considered to be down.
example: it works
check_passive:
type: boolean
default: true
description: >
If true, any response from this backend with a `5xx` status code will be
enough for it to be considered unhealthy and taken out of rotation.
example: true
x-linode-cli-display: 6
proxy_protocol:
description: >
ProxyProtocol is a TCP extension that sends initial TCP connection
information such as source/destination IPs and ports to backend devices.
This information would be lost otherwise. Backend devices must be
configured to work with ProxyProtocol if enabled.
* If ommited, or set to `none`, the NodeBalancer doesn't send any auxilary
data over TCP connections. This is the default.
* If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol.
* If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol.
type: string
enum:
- none
- v1
- v2
example: none
default: none
cipher_suite:
type: string
enum:
- recommended
- legacy
default: recommended
description: >
What ciphers to use for SSL connections served by this NodeBalancer.
* `legacy` is considered insecure and should only be used if necessary.
example: recommended
x-linode-cli-display: 7
x-linode-cli-color:
legacy: red
default_: white
nodebalancer_id:
type: integer
description: >
The ID for the NodeBalancer this config belongs to.
example: 12345
readOnly: true
ssl_commonname:
type: string
description: >
The read-only common name automatically derived from the SSL certificate assigned to this
NodeBalancerConfig. Please refer to this field to verify that the appropriate
certificate is assigned to your NodeBalancerConfig.
example: www.example.com
readOnly: true
x-linode-cli-display: 8
ssl_fingerprint:
type: string
description: >
The read-only SHA1-encoded fingerprint automatically derived from the SSL certificate assigned to this
NodeBalancerConfig. Please refer to this field to verify that the appropriate
certificate is assigned to your NodeBalancerConfig.
example: 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13
readOnly: true
x-linode-cli-display: 9
ssl_cert:
type: string
format: ssl-cert
nullable: true
description: |
The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL
certificate and Certificate Authority chain) that should be served on this
NodeBalancerConfig's port.
Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI).
[Diffie-Hellman Parameters](/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy.
The contents of this field will not be shown in any responses that display
the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field
appears.
The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig
response are automatically derived from your certificate. Please refer to these fields to
verify that the appropriate certificate was assigned to your NodeBalancerConfig.
example: <REDACTED>
ssl_key:
type: string
format: ssl-key
nullable: true
description: |
The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field.
Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI).
The contents of this field will not be shown in any responses that display
the NodeBalancerConfig. Instead, `<REDACTED>` will be printed where the field
appears.
The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig
response are automatically derived from your certificate. Please refer to these fields to
verify that the appropriate certificate was assigned to your NodeBalancerConfig.
example: <REDACTED>
nodes_status:
type: object
description: >
A structure containing information about the health of the backends
for this port. This information is updated periodically as checks
are performed against backends.
readOnly: true
x-linode-cli-display: 10
properties:
up:
type: integer
description: >
The number of backends considered to be "UP" and healthy, and that
are serving requests.
example: 4
readOnly: true
down:
type: integer
description: >
The number of backends considered to be "DOWN" and unhealthy. These
are not in rotation, and not serving requests.
example: 0
readOnly: true
NodeBalancerNode:
type: object
description: >
A NodeBalancerNode represents a single backend serving requests for a single
port of a NodeBalancer. Nodes are specific to NodeBalancer Configs, and serve
traffic over their private IP. If the same Linode is serving traffic for more
than one port on the same NodeBalancer, one NodeBalancer Node is required for
each config (port) it should serve requests on. For example, if you have
four backends, and each should response to both HTTP and HTTPS requests, you
will need two NodeBalancerConfigs (port 80 and port 443) and four backends
each - one for each of the Linodes serving requests for that port.
properties:
id:
type: integer
description: This node's unique ID.
example: 54321
readOnly: true
x-linode-cli-display: 1
address:
type: string
format: ip
description: >
The private IP Address where this backend can be reached. This _must_
be a private IP address.
example: 192.168.210.120:80
x-linode-cli-display: 3
label:
type: string
minLength: 3
maxLength: 32
pattern: '[a-zA-Z0-9-_.]{3,32}'
description: >
The label for this node. This is for display purposes only.
example: node54321
x-linode-cli-display: 2
status:
type: string
enum:
- unknown
- UP
- DOWN
description: >
The current status of this node, based on the configured checks
of its NodeBalancer Config.
example: UP
readOnly: true
x-linode-cli-display: 4
x-linode-cli-color:
UP: green
unknown: yellow
DOWN: red
default_: white
weight:
type: integer
minimum: 1
maximum: 255
description: >
Used when picking a backend to serve a request and is not pinned to
a single backend yet. Nodes with a higher weight will receive more
traffic.
example: 50
x-linode-cli-display: 5
mode:
type: string
enum:
- accept
- reject
- drain
- backup
description: >
The mode this NodeBalancer should use when sending traffic to this backend.
* If set to `accept` this backend is accepting traffic.
* If set to `reject` this backend will not receive traffic.
* If set to `drain` this backend will not receive _new_ traffic, but connections already
pinned to it will continue to be routed to it.
* If set to `backup`, this backend will only receive traffic if all `accept` nodes
are down.
example: accept
x-linode-cli-display: 6
config_id:
type: integer
description: >
The NodeBalancer Config ID that this Node belongs to.
example: 4567
readOnly: true
nodebalancer_id:
type: integer
description: >
The NodeBalancer ID that this Node belongs to.
example: 12345
readOnly: true
NodeBalancerStats:
type: object
description: >
Stats for this NodeBalancer.
properties:
data:
type: object
description: >
The data returned about this NodeBalancers.
properties:
connections:
type: array
description: >
An array of key/value pairs representing unix timestamp and
reading for connections to this NodeBalancer.
items:
type: number
example:
- 1526391300000
- 0
traffic:
type: object
description: >
Traffic statistics for this NodeBalancer.
properties:
in:
type: array
description: >
An array of key/value pairs representing unix timestamp and
reading for inbound traffic.
items:
type: number
example:
- 1526391300000
- 631.21
out:
type: array
description: >
An array of key/value pairs representing unix timestamp and
reading for outbound traffic.
items:
type: number
example:
- 1526391300000
- 103.44
title:
type: string
description: >
The title for the statistics generated in this response.
example: linode.com - balancer12345 (12345) - day (5 min avg)
Notification:
type: object
description: >
An important, often time-sensitive item related to your Account.
properties:
entity:
type: object
readOnly: true
description: Detailed information about the Notification.
properties:
id:
type: integer
description: >
The unique ID of the Notification's entity, based on the entity
type.
example: 3456
label:
type: string
description: >
The current label for this Notification's entity.
example: Linode not booting.
type:
type: string
description: The type of entity this is related to.
example: ticket
url:
type: string
description: >
The URL where you can access the object this Notification is for.
If a relative URL, it is relative to the domain you retrieved the
Notification from.
example: /support/tickets/3456
label:
type: string
description: >
A short description of this Notification.
example: You have an important ticket open!
readOnly: true
x-linode-cli-display: 1
message:
type: string
readOnly: true
description: A human-readable description of the Notification.
example: You have an important ticket open!
x-linode-cli-display: 2
body:
type: string
readOnly: true
description: >
A full description of this Notification, in markdown format. Not all
Notifications include bodies.
nullable: true
example: null
type:
type: string
enum:
- migration_scheduled
- migration_imminent
- migration_pending
- reboot_scheduled
- outage
- payment_due
- ticket_important
- ticket_abuse
- notice
- maintenance
- promotion
readOnly: true
description: The type of Notification this is.
example: ticket_important
severity:
type: string
enum:
- minor
- major
- critical
description: >
The severity of this Notification. This field can be used to
decide how prominently to display the Notification, what color
to make the display text, etc.
example: major
readOnly: true
x-linode-cli-display: 3
x-linode-cli-color:
critical: b
minor: blue
default_: white
when:
type: string
readOnly: true
format: date-time
description: >
If this Notification is of an Event that will happen at a fixed,
future time, this is when the named action will be taken. For
example, if a Linode is to be migrated in response to a
Security Advisory, this field will contain the approximate time the
Linode will be taken offline for migration.
example: null
x-linode-cli-display: 4
x-linode-cli-color:
None: black
default_: white
until:
type: string
format: date-time
description: >
If this Notification has a duration, this will be the ending time
for the Event/action. For example, if there is scheduled
maintenance for one of our systems, `until` would be set to the end
of the maintenance window.
example: null
readOnly: true
x-linode-cli-display: 5
x-linode-cli-color:
None: black
default_: white
OAuthClient:
type: object
description: >
A third-party application registered to Linode that users may log into
with their Linode account through our authentication server at
<a target="_top" href="https://login.linode.com">https://login.linode.com</a>. Using an OAuth Client, a third-party
developer may be given access to some, or all, of a User's account for
the purposes of their application.
properties:
id:
type: string
description: >
The OAuth Client ID. This is used to identify the client, and is a
publicly-known value (it is not a secret).
example: 2737bf16b39ab5d7b4a1
readOnly: true
x-linode-cli-display: 1
redirect_uri:
type: string
format: url
description: >
The location a successful log in from <a target="_top" href="https://login.linode.com">https://login.linode.com</a> should be
redirected to for this client. The receiver of this redirect should be
ready to accept an OAuth exchange code and finish the OAuth exchange.
example: https://example.org/oauth/callback
x-linode-cli-display: 5
label:
x-linode-filterable: true
type: string
minLength: 1
maxLength: 512
description: >
The name of this application. This will be presented to users when they
are asked to grant it access to their Account.
example: Test_Client_1
x-linode-cli-display: 2
status:
type: string
enum:
- active
- disabled
- suspended
description: >
The status of this application. `active` by default.
example: active
readOnly: true
x-linode-cli-display: 3
x-linode-cli-color:
suspended: red
default_: white
secret:
type: string
description: >
The OAuth Client secret, used in the OAuth exchange. This is returned
as `<REDACTED>` except when an OAuth Client is created or its secret
is reset. This is a secret, and should not be shared or disclosed
publicly.
example: <REDACTED>
readOnly: true
thumbnail_url:
type: string
nullable: true
format: url
description: >
The URL where this client's thumbnail may be viewed, or `null` if this client
does not have a thumbnail set.
example: https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail
readOnly: true
public:
x-linode-filterable: true
type: boolean
default: false
description: >
If this is a public or private OAuth Client. Public clients have a slightly
different authentication workflow than private clients. See the
<a target="_top" href="https://oauth.net/2/">OAuth spec</a> for more details.
example: false
x-linode-cli-display: 4
ObjectStorageBucket:
type: object
description: >
An Object Storage Bucket. This should be accessed primarily through the
S3 API; [click here for more information](https://docs.ceph.com/en/latest/radosgw/s3/#api).
properties:
created:
type: string
format: date-time
description: When this bucket was created.
example: 2019-01-01T01:23:45
cluster:
type: string
description: The ID of the Object Storage Cluster this bucket is in.
example: us-east-1
label:
type: string
description: The name of this bucket.
example: example-bucket
hostname:
type: string
description: >
The hostname where this bucket can be accessed. This hostname
can be accessed through a browser if the bucket is made public.
example: example-bucket.us-east-1.linodeobjects.com
size:
type: integer
description: The size of the bucket in bytes.
example: 188318981
objects:
type: integer
description: >
The number of objects stored in this bucket.
example: 4
ObjectStorageObject:
type: object
description: >
An Object in Object Storage, or a "prefix" that contains one
or more objects when a `delimiter` is used.
properties:
name:
type: string
description: >
The name of this object or prefix.
example: example
etag:
type: string
description: >
An MD-5 hash of the object. `null` if this object represents a prefix.
example: 9f254c71e28e033bf9e0e5262e3e72ab
last_modified:
type: string
format: date-time
description: >
The date and time this object was last modified. `null` if this object
represents a prefix.
example: 2019-01-01T01:23:45
owner:
type: string
description: >
The owner of this object, as a UUID. `null` if this object represents
a prefix.
example: bfc70ab2-e3d4-42a4-ad55-83921822270c
size:
type: integer
description: >
The size of this object, in bytes. `null` if this object represents
a prefix.
example: 123
next_marker:
type: string
description: >
Returns the value you should pass to the `marker` query parameter to get the next page of objects.
If there is no next page, `null` will be returned.
example: bd021c21-e734-4823-97a4-58b41c2cd4c8.892602.184
nullable: true
is_truncated:
type: boolean
description: Designates if there is another page of bucket objects.
example: true
ObjectStorageCluster:
type: object
description: An Object Storage Cluster
properties:
id:
type: string
description: The unique ID for this cluster.
example: us-east-1
domain:
type: string
description: The base URL for this cluster, used for connecting with third-party clients.
example: us-east-1.linodeobjects.com
status:
type: string
enum:
- available
- unavailable
description: This cluster's status.
example: available
region:
type: string
description: The region where this cluster is located.
example: us-east
static_site_domain:
type: string
description: The base URL for this cluster used when hosting static sites.
example: website-us-east-1.linodeobjects.com
ObjectStorageKey:
type: object
description: A keypair used to communicate with the Object Storage S3 API.
properties:
id:
type: integer
description: This keypair's unique ID
example: 123
readOnly: true
label:
type: string
description: The label given to this key. For display purposes only.
example: my-key
access_key:
type: string
description: This keypair's access key. This is not secret.
example: KVAKUTGBA4WTR2NSJQ81
readOnly: true
secret_key:
type: string
description: This keypair's secret key. Only returned on key creation.
example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw
readOnly: true
limited:
type: boolean
description: Whether or not this key is a limited access key. Will return `false` if this key grants full access to all buckets on the user's account.
example: true
readOnly: true
bucket_access:
type: array
description: >
Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions.
Limited Access Keys can:
* [list all buckets](/docs/api/object-storage/#object-storage-buckets-list) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket.
* [create new buckets](/docs/api/object-storage/#object-storage-bucket-create), but do not have any access to the buckets it creates, unless explicitly given access to them.
**Note:** You can create an Object Storage Limited Access Key without access to any buckets.
This is achieved by sending a request with an empty `bucket_access` array.
**Note:** If this field is omitted, a regular unlimited access key is issued.
items:
type: object
properties:
cluster:
type: string
description: The Object Storage cluster where a bucket to which the key is granting access is hosted.
example: ap-south-1
bucket_name:
type: string
description: The unique label of the bucket to which the key will grant limited access.
example: example-bucket
permissions:
type: string
enum:
- read_write
- read_only
description: This Limited Access Key's permissions for the selected bucket.
example: read_only
ObjectStorageSSL:
type: object
required:
- certificate
- private_key
description: >
Upload a TLS/SSL certificate and private key to be served when you visit your Object Storage bucket via HTTPS.
properties:
certificate:
type: string
description: |
Your Base64 encoded and PEM formatted SSL certificate.
Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI)
example: "-----BEGIN CERTIFICATE-----\nCERTIFICATE_INFORMATION\n-----END CERTIFICATE-----"
private_key:
type: string
description: |
The private key associated with this TLS/SSL certificate.
Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI)
example: "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY_INFORMATION\n-----END PRIVATE KEY-----"
ObjectStorageSSLResponse:
type: object
description: >
If this Object Storage bucket has a corresponding TLS/SSL Certificate.
properties:
ssl:
type: boolean
description: >
A boolean indicating if this Bucket has a corresponding TLS/SSL certificate that was uploaded by an Account user.
example: true
readOnly: true
PaginationEnvelope:
type: object
description: >
An envelope for paginated response. When accessing a collection through a GET endpoint, the
results are wrapped in this envelope which includes metadata about those results. Results
are presented within a `data` array. See [Pagination](/docs/api/#pagination) for more information.
properties:
pages:
type: integer
readOnly: true
description: The total number of [pages](/docs/api/#pagination).
example: 1
page:
type: integer
readOnly: true
description: The current [page](/docs/api/#pagination).
example: 1
results:
type: integer
readOnly: true
description: The total number of results.
example: 1
Payment:
type: object
description: Payment object response.
properties:
id:
type: integer
readOnly: true
description: The unique ID of the Payment.
example: 123
x-linode-cli-display: 1
date:
type: string
readOnly: true
format: date-time
description: When the Payment was made.
example: '2018-01-15T00:01:01'
x-linode-cli-display: 2
usd:
type: integer
readOnly: true
description: The amount, in US dollars, of the Payment.
example: '120.50'
x-linode-cli-display: 3
PaymentMethod:
type: object
description: Payment Method Response Object.
properties:
id:
type: integer
description: The unique ID of this Payment Method.
example: 123
x-linode-cli-display: 1
type:
type: string
enum:
- credit_card
- google_pay
- paypal
description: The type of Payment Method.
example: 'credit_card'
x-linode-cli-display: 2
is_default:
type: boolean
description: |
Whether this Payment Method is the default method for automatically processing service charges.
example: true
x-linode-cli-display: 3
created:
type: string
readOnly: true
format: date-time
description: When the Payment Method was added to the Account.
example: '2018-01-15T00:01:01'
data:
x-linode-cli-format: json
x-linode-cli-display: 4
oneOf:
- x-linode-ref-name: "Credit Card"
$ref: '#/components/schemas/CreditCardData'
- x-linode-ref-name: "Google Pay"
$ref: '#/components/schemas/GooglePayData'
- x-linode-ref-name: "Paypal"
$ref: '#/components/schemas/PayPalData'
discriminator:
propertyName: type
CreditCardData:
type: object
description: Credit card information.
properties:
card_type:
type: string
readOnly: true
description: The type of credit card.
example: "Discover"
last_four:
type: string
readOnly: true
description: The last four digits of the credit card number.
example: "1234"
expiry:
type: string
readOnly: true
format: MM/YYYY
description: The expiration month and year of the credit card.
example: 06/2022
GooglePayData:
type: object
description: Google Pay information.
properties:
card_type:
type: string
readOnly: true
description: The type of credit card.
example: "Discover"
last_four:
type: string
readOnly: true
description: The last four digits of the credit card number.
example: "1234"
expiry:
type: string
readOnly: true
format: MM/YYYY
description: The expiration month and year of the credit card.
example: 06/2022
PayPalData:
type: object
description: PayPal information.
properties:
email:
type: string
readOnly: true
description: The email address associated with your PayPal account.
example: "example@linode.com"
paypal_id:
type: string
readOnly: true
description: PayPal Merchant ID associated with your PayPal account.
example: "ABC1234567890"
PaymentRequest:
type: object
required:
- usd
description: Payment object request.
properties:
cvv:
type: string
description: >
CVV (Card Verification Value) of the credit card to be used for
the Payment. Required if paying by credit card.
example: '123'
usd:
type: string
pattern: ^\$?\d+\.\d{2}$
description: |
The amount in US Dollars of the Payment.
* Can begin with or without `$`.
* Commas (`,`) are not accepted.
* Must end with a decimal expression, such as `.00` or `.99`.
* Minimum: `$5.00` or the Account balance, whichever is lower.
* Maximum: `$2000.00` or the Account balance up to `$50000.00`, whichever is greater.
example: '$120.50'
payment_method_id:
type: integer
description: >
The ID of the Payment Method to apply to the Payment.
example: 123
PayPal:
type: object
required:
- cancel_url
- redirect_url
- usd
description: >
An object representing the staging of a Payment via PayPal.
properties:
cancel_url:
type: string
description: The URL to have PayPal redirect to when Payment is cancelled.
example: https://example.org
redirect_url:
type: string
description: The URL to have PayPal redirect to when Payment is approved.
example: https://example.org
usd:
type: string
description: The payment amount in USD. Minimum accepted value of $5 USD.
Maximum accepted value of $500 USD or credit card payment limit; whichever value is highest. PayPal's
maximum transaction limit is $10,000 USD.
example: '120.50'
PayPalExecute:
type: object
required:
- payer_id
- payment_id
description: >
An object representing an execution of Payment to PayPal to capture the
funds and credit your Linode Account.
properties:
payer_id:
type: string
description: >
The PayerID returned by PayPal during the transaction authorization
process.
example: ABCDEFGHIJKLM
payment_id:
type: string
description: >
The PaymentID returned from
[POST /account/payments/paypal](/docs/api/account/#paypal-payment-stage) that has
been approved with PayPal.
example: PAY-1234567890ABCDEFGHIJKLMN
PersonalAccessToken:
type: object
description: >
A Personal Access Token is a token generated manually to access the API
without going through an OAuth login. Personal Access Tokens can have
scopes just like OAuth tokens do, and are commonly used to give access
to command-line tools like the Linode CLI, or when writing your own
integrations.
properties:
id:
type: integer
description: >
This token's unique ID, which can be used to revoke it.
example: 123
readOnly: true
x-linode-cli-display: 1
scopes:
type: string
format: oauth-scopes
description: >
The scopes this token was created with. These define what parts of
the Account the token can be used to access. Many command-line tools,
such as the <a target="_top" href="https://github.com/linode/linode-cli">Linode CLI</a>,
require tokens with access to `*`. Tokens with more restrictive scopes
are generally more secure.
example: '*'
readOnly: true
x-linode-cli-display: 3
created:
type: string
format: date-time
description: >
The date and time this token was created.
x-linode-filterable: true
example: 2018-01-01T00:01:01
readOnly: true
x-linode-cli-display: 4
label:
type: string
minLength: 1
maxLength: 100
description: >
This token's label. This is for display purposes only, but can be used to
more easily track what you're using each token for.
x-linode-filterable: true
example: linode-cli
x-linode-cli-display: 2
token:
type: string
description: >
The token used to access the API. When the token is created, the full token
is returned here. Otherwise, only the first 16 characters are returned.
example: abcdefghijklmnop
readOnly: true
x-linode-cli-display: 5
expiry:
type: string
format: date-time
description: >
When this token will expire. Personal Access Tokens cannot be renewed, so
after this time the token will be completely unusable and a new token will
need to be generated. Tokens may be created with "null" as their expiry
and will never expire unless revoked.
x-linode-cli-display: 6
example: '2018-01-01T13:46:32'
readOnly: true
Profile:
type: object
description: >
A Profile represents your User in our system. This is where you can change
information about your User. This information is available to any OAuth Client
regardless of requested scopes, and can be used to populate User information
in third-party applications.
properties:
uid:
type: integer
description: >
Your unique ID in our system. This value will never change, and can
safely be used to identify your User.
example: 1234
readOnly: true
username:
type: string
description: >
Your username, used for logging in to our system.
example: exampleUser
readOnly: true
x-linode-cli-display: 1
email:
type: string
format: email
description: >
Your email address. This address will be used for communication with Linode
as necessary.
example: example-user@gmail.com
x-linode-cli-display: 2
verified_phone_number:
type: string
format: phone
readOnly: true
description: |
The phone number verified for this Profile with the **Phone Number Verify** ([POST /profile/phone-number/verify](/docs/api/profile/#phone-number-verify)) command.
`null` if this Profile has no verified phone number.
example: "+5555555555"
timezone:
type: string
description: >
The timezone you prefer to see times in. This is not used by the API directly.
It is provided for the benefit of clients such as the Linode Cloud Manager and
other clients built on the API. All times returned by the API are in UTC.
example: US/Eastern
email_notifications:
type: boolean
description: >
If true, you will receive email notifications about account activity. If false,
you may still receive business-critical communications through email.
example: true
referrals:
type: object
description: |
Information about your status in our referral program.
This information becomes accessible after this Profile's Account has established at least $25.00 USD of total payments.
readOnly: true
properties:
code:
type: string
description: >
Your referral code. If others use this when signing up for Linode, you will
receive account credit.
example: 871be32f49c1411b14f29f618aaf0c14637fb8d3
readOnly: true
url:
type: string
format: url
description: >
Your referral url, used to direct others to sign up for Linode with your referral
code.
example: https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3
readOnly: true
total:
type: integer
description: >
The number of users who have signed up with your referral code.
example: 0
readOnly: true
completed:
type: integer
description: >
The number of completed signups with your referral code.
example: 0
readOnly: true
pending:
type: integer
description: >
The number of pending signups with your referral code. You will not receive
credit for these signups until they are completed.
example: 0
readOnly: true
credit:
type: integer
description: >
The amount of account credit in US Dollars issued to you through
the referral program.
example: 0
readOnly: true
ip_whitelist_enabled:
deprecated: true
type: boolean
description: >
If true, logins for your User will only be allowed from whitelisted IPs.
This setting is currently deprecated, and cannot be enabled.
If you disable this setting, you will not be able to re-enable it.
example: false
lish_auth_method:
type: string
enum:
- password_keys
- keys_only
- disabled
description: >
The authentication methods that are allowed when connecting to
[the Linode Shell (Lish)](/docs/platform/manager/using-the-linode-shell-lish/).
* `keys_only` is the most secure if you intend to use Lish.
* `disabled` is recommended if you do not intend to use Lish at
all.
* If this account's Cloud Manager authentication type is set to a Third-Party Authentication method, `password_keys` cannot
be used as your Lish authentication method. To view this account's Cloud Manager `authentication_type` field, send a request
to the [View Profile](/docs/api/profile/#profile-view) endpoint.
example: keys_only
authorized_keys:
type: array
nullable: true
items:
type: string
format: ssh-key
description: >
The list of SSH Keys authorized to use Lish for your User. This value is ignored if
`lish_auth_method` is "disabled."
example: null
two_factor_auth:
type: boolean
description: >
If true, logins from untrusted computers will require Two Factor
Authentication. See [/profile/tfa-enable](/docs/api/profile/#two-factor-secret-create) to
enable Two Factor Authentication.
example: true
x-linode-cli-display: 4
restricted:
type: boolean
description: >
If true, your User has restrictions on what can be accessed on your
Account. To get details on what entities/actions you can
access/perform, see [/profile/grants](/docs/api/profile/#grants-list).
example: false
x-linode-cli-display: 3
authentication_type:
type: string
enum:
- password
- github
description: |
This account's Cloud Manager authentication type. Authentication types are chosen through
Cloud Manager and authorized when logging into your account. These authentication types are either
the user's password (in conjunction with their username), or the name of their
indentity provider such as GitHub. For example, if a user:
- Has never used Third-Party Authentication, their authentication type will be `password`.
- Is using Third-Party Authentication, their authentication type will be the name of their Identity Provider (eg. `github`).
- Has used Third-Party Authentication and has since revoked it, their authentication type will be `password`.
**Note:** This functionality may not yet be available in Cloud Manager.
See the [Cloud Manager Changelog](/changelog/cloud-manager/) for the latest updates.
example: password
readOnly: true
Promotion:
type: object
readOnly: true
description: |
Promotions generally
offer a set amount of credit that can be used toward your Linode
services, and the promotion expires after a specified date. As well,
a monthly cap on the promotional offer is set.
Simply put, a promotion offers a certain amount of credit every
month, until either the expiration date is passed, or until the total
promotional credit is used, whichever comes first.
properties:
credit_monthly_cap:
x-linode-cli-display: 5
type: string
description: >
The amount available to spend per month.
example: "10.00"
credit_remaining:
x-linode-cli-display: 3
type: string
description: >
The total amount of credit left for this promotion.
example: "50.00"
description:
type: string
description: >
A detailed description of this promotion.
example: "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends."
expire_dt:
x-linode-cli-display: 2
type: string
description: >
When this promotion's credits expire.
example: '2018-01-31T23:59:59'
image_url:
type: string
description: >
The location of an image for this promotion.
example: "https://linode.com/10_a_month_promotion.svg"
summary:
x-linode-cli-display: 10
type: string
description: >
Short details of this promotion.
example: "$10 off your Linode a month!"
this_month_credit_remaining:
x-linode-cli-display: 4
type: string
description: >
The amount of credit left for this month for this promotion.
example: "10.00"
service_type:
x-linode-cli-display: 1
type: string
enum:
- all
- backup
- blockstorage
- db_mysql
- ip_v4
- linode
- linode_disk
- linode_memory
- longview
- managed
- nodebalancer
- objectstorage
- transfer_tx
description: >
The service to which this promotion applies.
example: "all"
Region:
type: object
description: An area where Linode services are available.
properties:
id:
readOnly: true
type: string
description: The unique ID of this Region.
example: us-east
x-linode-cli-display: 1
country:
type: string
description: The country where this Region resides.
example: us
readOnly: true
x-linode-cli-display: 2
capabilities:
type: array
items:
type: string
description: >
A list of capabilities of this region.
example:
- Linodes
- NodeBalancers
- Block Storage
- Object Storage
readOnly: true
x-linode-cli-display: 3
status:
type: string
description: >
This region's current operational status.
example: ok
enum:
- ok
- outage
readOnly: true
x-linode-cli-display: 4
resolvers:
type: object
readOnly: true
x-linode-cli-display: 5
properties:
ipv4:
type: string
description: >
The IPv4 addresses for this region's DNS resolvers, separated by commas.
example: "192.0.2.0,192.0.2.1"
readOnly: true
ipv6:
type: string
description: >
The IPv6 addresses for this region's DNS resolvers, separated by commas.
example: "2001:0db8::,2001:0db8::1"
readOnly: true
RescueDevices:
type: object
properties:
sda:
$ref: '#/components/schemas/Device'
sdb:
$ref: '#/components/schemas/Device'
sdc:
$ref: '#/components/schemas/Device'
sdd:
$ref: '#/components/schemas/Device'
sde:
$ref: '#/components/schemas/Device'
sdf:
$ref: '#/components/schemas/Device'
sdg:
$ref: '#/components/schemas/Device'
StackScript:
type: object
description: >
A StackScript enables you to quickly deploy a
fully-configured application in an automated manner.
properties:
id:
type: integer
description: The unique ID of this StackScript.
example: 10079
readOnly: true
x-linode-cli-display: 1
username:
type: string
description: >
The User who created the StackScript.
example: myuser
readOnly: true
x-linode-cli-display: 2
user_gravatar_id:
type: string
description: >
The Gravatar ID for the User who created the StackScript.
example: a445b305abda30ebc766bc7fda037c37
readOnly: true
label:
x-linode-filterable: true
type: string
description: >
The StackScript's label is for display purposes only.
example: a-stackscript
minLength: 3
maxLength: 128
x-linode-cli-display: 3
description:
x-linode-filterable: true
type: string
description: >
A description for the StackScript.
example: >
This StackScript installs and configures MySQL
images:
type: array
description: |
An array of Image IDs. These are the images that can be deployed
with this Stackscript.
`any/all` indicates that all available image distributions are accepted.
items:
type: string
example:
- linode/debian9
- linode/debian8
x-linode-cli-display: 4
deployments_total:
x-linode-filterable: true
type: integer
description: >
The total number of times this StackScript has been deployed.
example: 12
readOnly: true
deployments_active:
type: integer
description: >
Count of currently active, deployed Linodes created from
this StackScript.
example: 1
readOnly: true
is_public:
x-linode-filterable: true
type: boolean
description: >
This determines whether other users can use your StackScript.
**Once a StackScript is made public, it cannot be made private.**
example: true
x-linode-cli-display: 5
created:
type: string
format: date-time
description: >
The date this StackScript was created.
readOnly: true
example: "2018-01-01T00:01:01"
x-linode-cli-display: 6
updated:
type: string
format: date-time
description: >
The date this StackScript was last updated.
readOnly: true
example: "2018-01-01T00:01:01"
x-linode-cli-display: 7
rev_note:
x-linode-filterable: true
type: string
description: >
This field allows you to add notes for the set of revisions made to
this StackScript.
example: Set up MySQL
script:
type: string
description: >
The script to execute when provisioning a new Linode with this StackScript.
example: >
"#!/bin/bash"
x-linode-cli-format: file
user_defined_fields:
type: array
description: >
This is a list of fields defined with a special syntax inside this StackScript
that allow for supplying customized parameters during deployment. See
<a target="_top" href="/docs/platform/stackscripts/#variables-and-udfs">Variables and UDFs</a>
for more information.
items:
$ref: '#/components/schemas/UserDefinedField'
readOnly: true
example:
label: Enter the DB password
name: DB_PASSWORD
example: hunter2
mine:
type: boolean
x-linode-filterable: true
description: |
Returns `true` if this StackScript is owned by the account of the user making the request, and the user
making the request is unrestricted or has access to this StackScript.
readOnly: true
example: true
StatsDataAvailable:
type: object
description: >
A collection of graph data returned for managed stats.
properties:
cpu:
type: array
description: CPU usage stats from the last 24 hours.
items:
$ref: '#/components/schemas/StatsData'
disk:
type: array
description: Disk usage stats from the last 24 hours.
items:
$ref: '#/components/schemas/StatsData'
swap:
type: array
description: Swap usage stats from the last 24 hours.
items:
$ref: '#/components/schemas/StatsData'
net_in:
type: array
description: Inbound network traffic stats from the last 24 hours.
items:
$ref: '#/components/schemas/StatsData'
net_out:
type: array
description: Outbound network traffic stats from the last 24 hours.
items:
$ref: '#/components/schemas/StatsData'
StatsDataUnavailable:
type: array
readOnly: true
description: >
An array of error messages if managed stats are unavaliable.
items:
type: string
example: Graphs are not yet available.
StatsData:
type: object
description: >
A stat data point.
properties:
x:
type: integer
readOnly: true
description: >
A stats graph data point.
example: 11513761600000
y:
type: integer
readOnly: true
description: >
A stats graph data point.
example: 29.94
SupportTicket:
type: object
description: >
A Support Ticket opened on your Account.
properties:
id:
type: integer
readOnly: true
description: >
The ID of the Support Ticket.
example: 11223344
x-linode-cli-display: 1
attachments:
type: array
description: >
A list of filenames representing attached files associated
with this Ticket.
readOnly: true
items:
type: string
example:
- screenshot.jpg
- screenshot.txt
closed:
x-linode-filterable: true
type: string
nullable: true
format: date-time
readOnly: true
description: >
The date and time this Ticket was closed.
example: '2015-06-04T16:07:03'
closable:
type: boolean
description: >
Whether the Support Ticket may be closed.
example: false
description:
type: string
readOnly: true
description: >
The full details of the issue or question.
minLength: 1
maxLength: 65000
example: >
I'm having trouble setting the root password on my Linode.
I tried following the instructions but something is not
working and I'm not sure what I'm doing wrong. Can you please
help me figure out how I can reset it?
x-linode-cli-display: 5
entity:
type: object
nullable: true
readOnly: true
description: >
The entity this Ticket was opened for.
x-linode-cli-display: 6
properties:
id:
type: integer
readOnly: true
description: >
The unique ID for this Ticket's entity.
example: 10400
label:
type: string
readOnly: true
description: >
The current label of this entity.
example: linode123456
type:
type: string
readOnly: true
description: >
The type of entity this is related to.
example: linode
url:
type: string
readOnly: true
description: >
The URL where you can access the object this event is
for. If a relative URL, it is relative to the domain you
retrieved the entity from.
example: /v4/linode/instances/123456
gravatar_id:
type: string
readOnly: true
description: >
The Gravatar ID of the User who opened this Ticket.
example: 474a1b7373ae0be4132649e69c36ce30
opened:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
The date and time this Ticket was created.
example: '2015-06-04T14:16:44'
x-linode-cli-display: 4
opened_by:
type: string
readOnly: true
description: >
The User who opened this Ticket.
example: some_user
x-linode-cli-display: 3
status:
type: string
readOnly: true
description: The current status of this Ticket.
enum:
- closed
- new
- open
example: open
summary:
type: string
readOnly: true
minLength: 1
maxLength: 64
description: >
The summary or title for this Ticket.
example: >
Having trouble resetting root password on my Linode
x-linode-cli-display: 2
updated:
x-linode-filterable: true
type: string
format: date-time
readOnly: true
description: >
The date and time this Ticket was last updated.
example: '2015-06-04T16:07:03'
updated_by:
type: string
nullable: true
readOnly: true
description: >
The User who last updated this Ticket.
example: some_other_user
SupportTicketReply:
type: object
description: >
An object representing a reply to a Support Ticket.
properties:
created:
type: string
format: date-time
readOnly: true
description: >
The date and time this Ticket reply was created.
example: '2015-06-02T14:31:41'
x-linode-cli-display: 3
created_by:
type: string
readOnly: true
description: >
The User who submitted this reply.
example: John Q. Linode
x-linode-cli-display: 2
description:
type: string
readOnly: true
description: >
The body of this Support Ticket reply.
example: >
Hello,\nI'm sorry to hear that you are having trouble resetting the
root password of your Linode. Just to be sure, have you tried to
follow the instructions in our online documentation? The link is here:\n
\nhttps://linode.com/docs/quick-answers/linode-platform/reset-the-root-password-on-your-linode/
\n\nIf you have, please reply with any additional steps you have also
taken.\n\nRegards, Linode Support Team
from_linode:
type: boolean
readOnly: true
description: >
If set to true, this reply came from a Linode employee.
example: true
gravatar_id:
type: string
readOnly: true
description: >
The Gravatar ID of the User who created this reply.
example: 474a1b7373ae0be4132649e69c36ce30
id:
type: integer
readOnly: true
description: >
The unique ID of this Support Ticket reply.
example: 11223345
x-linode-cli-display: 1
SupportTicketRequest:
type: object
required:
- summary
- description
description: >
An object representing a created Support Ticket - a question or issue
and request for help from the Linode support team.
Only one of the ID attributes (`linode_id`, `domain_id`, etc.) can be set
on a single Support Ticket.
properties:
description:
type: string
description: >
The full details of the issue or question.
minLength: 1
maxLength: 65000
example: >
I'm having trouble setting the root password on my Linode.
I tried following the instructions but something is not
working and I'm not sure what I'm doing wrong. Can you please
help me figure out how I can reset it?
database_id:
type: integer
description: >
The ID of the Managed Database this ticket is regarding, if relevant.
domain_id:
type: integer
description: >
The ID of the Domain this ticket is regarding, if relevant.
example: null
firewall_id:
type: integer
description: >
The ID of the Firewall this ticket is regarding, if relevant.
linode_id:
type: integer
description: >
The ID of the Linode this ticket is regarding, if relevant.
example: 123
lkecluster_id:
type: integer
description: >
The ID of the Kubernetes cluster this ticket is regarding, if relevant.
example: 123
longviewclient_id:
type: integer
description: >
The ID of the Longview client this ticket is regarding, if relevant.
example: null
nodebalancer_id:
type: integer
description: >
The ID of the NodeBalancer this ticket is regarding, if relevant.
example: null
summary:
type: string
minLength: 1
maxLength: 64
description: >
The summary or title for this SupportTicket.
example: >
Having trouble resetting root password on my Linode
managed_issue:
type: boolean
description: >
Designates if this ticket is related to a
[Managed service](https://www.linode.com/products/managed/).
If `true`, the following constraints will apply:
* No ID attributes (i.e. `linode_id`, `domain_id`, etc.) should be provided with this
request.
* Your account must have a [Managed service enabled](/docs/api/managed/#managed-service-enable).
example: false
volume_id:
type: integer
description: >
The ID of the Volume this ticket is regarding, if relevant.
example: null
vlan:
type: string
description: |
The label of the VLAN this ticket is regarding, if relevant. To view your VLANs, use the VLANs List ([GET /networking/vlans](/docs/api/networking/#vlans-list)) endpoint.
Requires a specified `region` to identify the VLAN.
example: null
region:
type: string
description: |
The [Region](/docs/api/regions/) ID for the associated VLAN this ticket is regarding.
Only allowed when submitting a VLAN ticket.
example: null
Transfer:
type: object
description: >
An object representing your network utilization for the current month,
in Gigabytes.
properties:
billable:
type: integer
readOnly: true
description: >
The amount of your transfer pool that is billable this billing cycle.
example: 0
x-linode-cli-display: 3
quota:
type: integer
readOnly: true
description: >
The amount of network usage allowed this billing cycle.
example: 9141
x-linode-cli-display: 1
used:
type: integer
readOnly: true
description: >
The amount of network usage you have used this billing cycle.
example: 2
x-linode-cli-display: 2
Tag:
type: object
description: >
A tag that has been applied to an object on your Account. Tags are
currently for organizational purposes only.
properties:
label:
type: string
description: >
A Label used for organization of objects on your Account.
example: example tag
User:
type: object
description: >
A User on your Account. Unrestricted users can log in and access information about
your Account, while restricted users may only access entities or perform
actions they've been granted access to.
properties:
username:
type: string
pattern: ^[a-zA-Z0-9]((?![_-]{2,})[a-zA-Z0-9-_])+[a-zA-Z0-9]$
minLength: 3
maxLength: 32
description: >
The User's username. This is used for logging in, and may also be
displayed alongside actions the User performs (for example, in Events
or public StackScripts).
x-linode-filterable: true
example: example_user
x-linode-cli-display: 1
email:
type: string
format: email
description: >
The email address for the User. Linode sends emails to this address for account management
communications. May be used for other communications as configured.
example: example_user@linode.com
x-linode-cli-display: 2
restricted:
type: boolean
description: >
If true, the User must be granted access to perform actions or access
entities on this Account. See User Grants View ([GET /account/users/{username}/grants](/docs/api/account/#users-grants-view))
for details on how to configure grants for a restricted User.
example: true
x-linode-cli-display: 3
ssh_keys:
type: array
readOnly: true
items:
type: string
description: |
A list of SSH Key labels added by this User.
Users can add keys with the SSH Key Add ([POST /profile/sshkeys](/docs/api/profile/#ssh-key-add)) command.
These keys are deployed when this User is included in the `authorized_users`
field of the following requests:
- Linode Create ([POST /linode/instances](/docs/api/linode-instances/#linode-create))
- Linode Rebuild ([POST /linode/instances/{linodeId}/rebuild](/docs/api/linode-instances/#linode-rebuild))
- Disk Create ([POST /linode/instances/{linodeId}/disks](/docs/api/linode-instances/#disk-create))
example:
- home-pc
- laptop
tfa_enabled:
type: boolean
readOnly: true
description: >
A boolean value indicating if the User has Two Factor Authentication (TFA)
enabled. See the Create Two Factor Secret ([POST /profile/tfa-enable](/docs/api/profile/#two-factor-secret-create))
endpoint to enable TFA.
UserDefinedField:
type: object
required:
- label
- name
- example
description: >
A custom field defined by the User with a special syntax within a
StackScript. Derived from the contents of the script.
properties:
label:
type: string
description: >
A human-readable label for the field that will serve as the input
prompt for entering the value during deployment.
example: Enter the password
readOnly: true
name:
type: string
description: >
The name of the field.
example: DB_PASSWORD
readOnly: true
example:
type: string
description: >
An example value for the field.
example: hunter2
readOnly: true
oneOf:
type: string
description: >
A list of acceptable single values for the field.
example: avalue,anothervalue,thirdvalue
readOnly: true
manyOf:
type: string
description: >
A list of acceptable values for the field in any quantity,
combination or order.
example: avalue,anothervalue,thirdvalue
readOnly: true
default:
type: string
description: >
The default value. If not specified, this value will be used.
readOnly: true
TrustedDevice:
type: object
description: >
A trusted device object represents an active Remember Me session with <a target="_top" href="https://login.linode.com">login.linode.com</a>.
properties:
id:
type: integer
description: The unique ID for this TrustedDevice
example: 123
readOnly: true
created:
type: string
format: date-time
description: >
When this Remember Me session was started. This corresponds to the time of login
with the "Remember Me" box checked.
example: "2018-01-01T01:01:01"
readOnly: true
expiry:
type: string
format: date-time
description: >
When this TrustedDevice session expires. Sessions typically last 30 days.
example: "2018-01-31T01:01:01"
readOnly: true
user_agent:
type: string
description: >
The User Agent of the browser that created this TrustedDevice session.
example: >
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/70.0.3538.77 Safari/537.36 Vivaldi/2.1.1337.36
readOnly: true
last_authenticated:
type: string
format: date-time
description: >
The last time this TrustedDevice was successfully used to authenticate to
<a target="_top" href="https://login.linode.com">login.linode.com</a>.
example: "2018-01-05T12:57:12"
readOnly: true
last_remote_addr:
type: string
description: >
The last IP Address to successfully authenticate with this TrustedDevice.
example: 12.34.56.78
readOnly: true
SecurityQuestion:
type: object
description: Single security question and response object.
properties:
id:
type: integer
description: The ID representing the security question.
example: 1
question:
type: string
readOnly: true
description: The security question.
example: "In what city were you born?"
response:
type: string
minLength: 3
maxLength: 17
description: |
The security question response.
example: "Gotham City"
SecurityQuestionsGet:
type: object
description: Security questions and responses object for GET operation.
properties:
security_questions:
type: array
items:
type: object
description: Single security question and response object for GET operation.
properties:
id:
$ref: '#/components/schemas/SecurityQuestion/properties/id'
question:
$ref: '#/components/schemas/SecurityQuestion/properties/question'
response:
$ref: '#/components/schemas/SecurityQuestion/properties/response'
SecurityQuestionsPost:
type: object
description: Security questions and responses object for POST operation.
properties:
security_questions:
type: array
items:
type: object
description: Single security question and response object for POST operation.
properties:
question_id:
$ref: '#/components/schemas/SecurityQuestion/properties/id'
response:
$ref: '#/components/schemas/SecurityQuestion/properties/response'
security_question:
$ref: '#/components/schemas/SecurityQuestion/properties/question'
ServiceTransfer:
type: object
description: >
An object representing a Service Transfer.
properties:
token:
x-linode-cli-display: 1
type: string
format: uuid
description: >
The token used to identify and accept or cancel this transfer.
example: "123E4567-E89B-12D3-A456-426614174000"
status:
x-linode-cli-display: 2
x-linode-filterable: true
x-linode-cli-color:
accepted: yellow
cancelled: red
completed: green
failed: red
pending: yellow
stale: red
default_: white
type: string
enum:
- accepted
- cancelled
- completed
- failed
- pending
- stale
description: |
The status of the transfer request.
`accepted`: The transfer has been accepted by another user and is currently in progress.
Transfers can take up to 3 hours to complete.
`cancelled`: The transfer has been cancelled by the sender.
`completed`: The transfer has completed successfully.
`failed`: The transfer has failed after initiation.
`pending`: The transfer is ready to be accepted.
`stale`: The transfer has exceeded its expiration date. It can no longer be accepted or
cancelled.
example: 'pending'
created:
type: string
format: date-time
description: >
When this transfer was created.
example: '2021-02-11T16:37:03'
updated:
type: string
format: date-time
description: >
When this transfer was last updated.
example: '2021-02-11T16:37:03'
is_sender:
x-linode-cli-display: 4
x-linode-filterable: true
type: boolean
description: >
If the requesting account created this transfer.
example: true
expiry:
x-linode-cli-display: 3
type: string
format: date-time
description: >
When this transfer expires. Transfers will automatically expire 24 hours after creation.
example: '2021-02-12T16:37:03'
entities:
type: object
description: >
A collection of the services to include in this transfer request, separated by type.
properties:
linodes:
x-linode-cli-display: 5
type: array
items:
type: integer
description: >
An array containing the IDs of each of the Linodes included in this transfer.
example: [111, 222]
SSHKey:
type: object
description: >
A credential object for authenticating a User's secure shell connection to a Linode.
properties:
id:
type: integer
description: >
The unique identifier of an SSH Key object.
example: 42
readOnly: true
label:
type: string
description: >
A label for the SSH Key.
example: "My SSH Key"
minLength: 0
maxLength: 64
ssh_key:
type: string
format: ssh-key
description: >
The public SSH Key, which is used to authenticate to the root user
of the Linodes you deploy.
readOnly: true
created:
type: string
format: date-time
description: >
The date this key was added.
example: "2018-01-01T00:01:01"
readOnly: true
SSHKeyRequest:
type: object
description: >
An object consisting of a user identified name as the `label` and the
generated key as the `ssh-key`.
properties:
label:
type: string
minLength: 1
maxLength: 64
description: >
A label for the key.
example: "My SSH Key"
ssh_key:
type: string
format: ssh-key
description: >
The public SSH Key, which is used to authenticate to the root user
of the Linodes you deploy.
Vlans:
type: object
description: >
A virtual local area network (VLAN) associated with your Account.
properties:
label:
type: string
description: The name of this VLAN.
example: vlan-example
readOnly: true
x-linode-cli-display: 2
x-linode-filterable: true
region:
type: string
description: |
This VLAN's data center region.
**Note:** Currently, a VLAN can only be assigned to a Linode
within the same data center region.
example: ap-west
readOnly: true
x-linode-cli-display: 1
x-linode-filterable: true
linodes:
type: array
description: >
An array of Linode IDs attached to this VLAN.
items:
type: integer
x-linode-cli-display: 3
readOnly: true
example:
- 111
- 222
created:
type: string
format: date-time
description: >
The date this VLAN was created.
example: "2020-01-01T00:01:01"
readOnly: true
Volume:
type: object
description: >
A Block Storage Volume associated with your Account.
properties:
id:
type: integer
description: The unique ID of this Volume.
example: 12345
readOnly: true
x-linode-cli-display: 1
label:
x-linode-filterable: true
type: string
description: >
The Volume's label is for display purposes only.
example: my-volume
minLength: 1
maxLength: 32
pattern: '^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$'
x-linode-cli-display: 2
filesystem_path:
type: string
description: >
The full filesystem path for the Volume based on the Volume's label.
Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label.
example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume
readOnly: true
status:
type: string
description: >
The current status of the volume. Can be one of:
* `creating` - the Volume is being created and is not yet available
for use.
* `active` - the Volume is online and available for use.
* `resizing` - the Volume is in the process of upgrading
its current capacity.
enum:
- creating
- active
- resizing
example: active
readOnly: true
x-linode-cli-display: 3
x-linode-cli-color:
active: green
contact_support: red
default_: yellow
size:
type: integer
description: >
The Volume's size, in GiB.
maximum: 10240
x-linode-cli-display: 4
example: 30
region:
$ref: '#/components/schemas/Region/properties/id'
x-linode-cli-display: 5
linode_id:
type: integer
nullable: true
description: >
If a Volume is attached to a specific Linode, the ID of that Linode
will be displayed here.
example: 12346
x-linode-cli-display: 6
linode_label:
type: string
nullable: true
description: >
If a Volume is attached to a specific Linode, the label of that Linode
will be displayed here.
example: linode123
x-linode-cli-display: 7
readOnly: true
created:
type: string
format: date-time
description: When this Volume was created.
example: '2018-01-01T00:01:01'
readOnly: true
updated:
type: string
format: date-time
description: When this Volume was last updated.
example: '2018-01-01T00:01:01'
readOnly: true
tags:
x-linode-filterable: true
description: >
An array of Tags applied to this object. Tags are for organizational
purposes only.
type: array
items:
type: string
example:
- example tag
- another example
hardware_type:
type: string
enum:
- hdd
- nvme
description: The storage type of this Volume.
example: nvme
readOnly: true
WarningObject:
type: object
description: >
An object for describing a single warning associated with a response.
properties:
title:
type: string
description: >
The general warning message.
example: Unable to reboot Linode.
details:
type: string
description: >
Specific information related to the warning.
example: Linode 123 could not be rebooted.
tags:
- name: Account
description: Use the Account endpoints to manage user settings, billing, and payments. You can also initiate and maintain OAuth client application authentication, enable the Linode Managed service, and create new users on your account.
- name: Databases
description: Managed Databases is Linode's fully-managed, high-performance database service. Use the Managed Databases endpoints to create and manage database clusters.
- name: Domains
description: Use the Domains endpoints to create and manage domains and domain records on your account.
- name: Images
description: Use the Images endpoints to capture, store, and manage custom Linode images.
- name: Linode Instances
description: Use the Linode Instances endpoints to create, configure, and manage your Linode instances. You can also manage the Linode Backup service; maintain and manage configuration profiles; create and maintain disks, intiate a host migration; view Linode Instance statistics; and more.
- name: Linode Types
description: Use the Linode Types endpoints to retrieve information about Linode plan types, including pricing information, hardware resources, and network transfer allotment.
- name: Linode Kubernetes Engine (LKE)
description: Linode Kubernetes Engine (LKE) is Linode's managed Kubernetes service. Use the LKE endpoints to create and manage Kubernetes clusters and their associated Node Pools.
- name: Longview
description: Longview is Linode's system-level monitoring and graphing service. Use the Longview endpoints to manage your Longview subscription and plan and to create and maintain Longview clients.
- name: Managed
description: Managed is Linode's incident response service. Use the Managed endpoints to register a service to be monitored by the Managed Service team, provide secure access to your managed services, view information about detected issues, and more.
- name: Networking
description: Use the Networking endpoints to view all IP addresses on your account, reorganize assigned IPv4 addresses, update RDNS, and configure IP sharing.
- name: NodeBalancers
description: NodeBalancers is Linode's load balancing service. Use the NodeBalancers endpoints to create and manage NodeBalancers. You can also create and maintain configurations; create and maintain nodes, and view statistics.
- name: Object Storage
description: Object Storage is Linode's S3-compatible data storage service. Use the Object Storage endpoints to create and maintaining buckets, add and remove objects from buckets, create and maintain Object Storage keys, and cancel the Object Storage service.
- name: Profile
description: Use the Profile endpoints to manage your Linode user profile preferences and security settings. This includes creating and maintaining personal access tokens, creating and maintaining SSH keys, confirming and enabling two-factor authentication, and updating user and profile preferences.
- name: Regions
description: Use the Regions endpoints to view information about the various Linode data center regions, including the service capabilities for each region, country, status, and more.
- name: StackScripts
description: Linode StackScripts allow you to create reusable scripts to configure new Linode instances. Use the StackScripts endpoints to create and manage StackScripts on your account.
- name: Support
description: Use the Support endpoints to open, view, and close Linode Support tickets. You can also create and manage your Support ticket replies.
- name: Tags
description: Tags allow you to organize and group your various Linode services. Use the Tags endpoints to create, assign, and delete your account tags.
- name: Volumes
description: Volumes is Linode's block storage service. Use the Volumes endpoints to create, attach, and manage your account Volumes.
