Linode API v4.166.0

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 OpenAPI website for more information.

Download the Linode OpenAPI Specification.

Changelog

View our Changelog 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 Linode Cloud Manager or the Create Personal Access Token endpoint.

All scopes for the OAuth security model ( defined below) apply to this security model as well.

Authentication

Security Scheme Type:HTTP
HTTP Authorization Schemebearer

OAuth

If you only need to access the Linode API for personal use, we recommend that you create a 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.

Before you implement OAuth in your application, you first need to create an OAuth client. You can do this with the Linode API or via the Cloud Manager:

  • 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, 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 and implicit flow.
PRIVATE WORKFLOWPUBLIC 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 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 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:

PARAMETERDESCRIPTION
client_idYour app’s client ID.
client_secretYour app’s client secret.
codeThe code you just received from the redirect.

You’ll get a response like this:

1
2
3
4
5
6
7
{
  "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:

PARAMETERDESCRIPTION
grant_typeThe grant type you’re using. Use “refresh_token” when refreshing access.
client_idYour app’s client ID.
client_secretYour app’s client secret.
refresh_tokenThe 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 TypeOAuth 2.0
Authorization URLhttps://login.linode.com/oauth/authorize
Token URLhttps://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.
  • databases:read_only - Allows access to GET Managed Databases on your Account.
  • databases:read_write - Allows access to all endpoints related to your Managed Databases.
  • 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 access 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.
  • 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.

Requests

Requests must be made over HTTPS to ensure transactions are encrypted. Data included in requests must be supplied in json format unless otherwise specified in the command description.

The following request methods are supported:

METHODUSAGE
GETRetrieves data about collections and individual resources.
POSTFor collections, creates a new resource of that type. Also used to perform actions on action endpoints.
PUTUpdates an existing resource.
DELETEDeletes a resource. This is a destructive action.
HEADReturns only the response header information of a GET request
OPTIONSProvides permitted communication options for a command

Responses

Response Status Codes

Actions will return one of the following HTTP response status codes:

STATUSDESCRIPTION
200 OKThe request was successful.
202 AcceptedThe request was successful, but processing has not been completed. The response body includes a “warnings” array containing the details of incomplete processes.
204 No ContentThe server successfully fulfilled the request and there is no additional content to send.
299 DeprecatedThe request was successful, but involved a deprecated endpoint. The response body includes a “warnings” array containing warning messages.
400 Bad RequestYou submitted an invalid request (missing parameters, etc.).
401 UnauthorizedYou failed to authenticate for this resource.
403 ForbiddenYou are authenticated, but don’t have permission to do this.
404 Not FoundThe resource you’re requesting does not exist.
429 Too Many RequestsYou’ve hit a rate limit.
500 Internal Server ErrorPlease open a Support Ticket.

Response Headers

There are many ways to access response header information for individual command URLs, depending on how you are accessing the Linode API. For example, to view HTTP response headers for the /regions endpoint when making requests with curl, use the -I or --head option as follows:

1
curl -I https://api.linode.com/v4/regions

Responses may include the following headers:

HEADERDESCRIPTIONEXAMPLE
Access-Control-Allow-CredentialsResponses to credentialed requests are exposed to frontend JavaScript code.true
Access-Control-Allow-HeadersAll permissible request headers for this endpoint.Authorization, Origin, X-Requested-With, Content-Type, Accept, X-Filter
Access-Control-Allow-MethodsPermissible HTTP methods for this endpointHEAD, GET, OPTIONS, POST, PUT, DELETE
Access-Control-Allow-OriginIndicates origin access permissions. The wildcard character * means any origin can access the resource.*
Access-Control-Expose-HeadersAvailable headers to include in response to cross-origin requests.X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Status
Cache-ControlControls caching in browsers and shared caches such as CDNs.private, max-age=60, s-maxage=60
Content-Security-PolicyControls which resources are allowed to load. By default, resources do not load.default-src ’none'
Content-TypeAll responses are in json format.application/json
Content-WarningA message containing instructions for successful requests that were not able to be completed.Please contact support for assistance.
Retry-AfterThe remaining time in seconds until the current rate limit window resets.60
Strict-Transport-SecurityEnforces HTTPS-only access until the returned time in seconds.max-age=31536000
VaryOptional request headers that affected the response content.Authorization, X-Filter
X-Accepted-OAuth-ScopesRequired scopes for accessing the requested command.linodes:read_only
X-Customer-UUIDA unique identifier for the account owning the the personal access token that was used for the request.ABCDEF01-3456-789A-BCDEF0123456789A
X-OAuth-ScopesAllowed scopes associated with the personal access token that was used for the request. A value of * indicates read/write access for all scope categories.images:read_write linodes:read_only
X-RateLimit-LimitThe maximum number of permitted requests during the rate limit window for this endpoint.800
X-RateLimit-RemainingThe remaining number of permitted requests in the current rate limit window.798
X-RateLimit-ResetThe time when the current rate limit window rests in UTC epoch seconds.1674747739
X-Spec-VersionThe current API version that handled the request.4.150.0

Errors

Success is indicated via Standard HTTP status codes. 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 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:

1
2
3
4
5
6
{
    "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:

1
2
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:

1
2
 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:

1
2
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:

OPERATORTYPEDESCRIPTION
+andarrayAll conditions must be true.
+orarrayOne condition must be true.
+gtnumberValue must be greater than number.
+gtenumberValue must be greater than or equal to number.
+ltnumberValue must be less than number.
+ltenumberValue must be less than or equal to number.
+containsstringGiven string must be in the value.
+neqstringDoes not equal the value.
+order_bystringAttribute to order the results by - must be filterable.
+orderstringEither “asc” or “desc”. Defaults to “asc”. Requires +order_by.

For example, filtering for Linode Types that offer memory equal to or higher than 61440:

1
2
3
4
5
6
7
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 which are either standard or highmem class, or have between 12 and 20 vcpus:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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).

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 commands have a rate limit of 800 requests per minute, and all GET commands that return paginated data collections have a rate limit of 400 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:

Creating Volumes has a dedicated rate limit of 25 requests per minute. That endpoint is:

Listing Images has a dedicated rate limit of 20 requests per minute. That endpoint is:

/stats endpoints have their own dedicated rate limits of 100 requests per minute. These endpoints are:

Object Storage endpoints have a dedicated rate limit of 750 requests per second. The Object Storage endpoints are:

Opening Support Tickets has a dedicated rate limit of 2 requests per minute. That endpoint is:

Accepting Service Transfers has a dedicated rate limit of 2 requests per minute. That endpoint is:

Rate Limit HTTP Response Headers

The Linode API includes the following HTTP response headers which are designed to help you avoid hitting rate limits which 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.

CLI (Command Line Interface)

The Linode CLI allows you to easily work with the API using intuitive and simple syntax. It requires a 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.