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.

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

The OAuth workflow is a three-step process to authenticate a User before an application can start making API calls on the User's behalf. If all you need is a Personal Access Token, feel free to skip ahead to the next section.

First, the User visits the application's website and is directed to log with Linode. The User is then redirected to Linode's authentication server and presented the scope levels the application is requesting. Once the User accepts the request for access, we redirect them back to the application's specified redirect URI with an access code.

Once the User has logged in to Linode and you have received an exchange code, you will need to exchange that access code for an Authorization 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 reponse like this:

{
  "scope": "linodes:read_write",
  "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c"
  "token_type": "bearer",
  "expires_in": 7200,
}

Included in the reponse is 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

Authentication

Security Scheme Type:Oauth2
AuthorizationCode Oauth FlowAuthorization URL: https://login.linode.com/oauth/authorize
Token URL: 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.
  • 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.
  • 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. 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.

Responses

Actions will return one following HTTP response status codes:

STATUSDESCRIPTION
200 OKThe request was successful.
204 No ContentThe server successfully fulfilled the request and there is no additional content to send.
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.

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:

{
    "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 100. 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:

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:

 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:

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:

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:

curl "https://api.linode.com/v4/linode/types" \
  -H '
    X-Filter: {
      "+or": [
        {
          "+or": [
            {
              "class": "standard"
            },
            {
              "class": "highmem"
            }
          ]
        },
        {
          "+and": [
            {
              "vcpus": {
                "+gte": 12
              }
            },
            {
              "vcpus": {
                "+lte": 20
              }
            }
          ]
        }
      ]
    }'

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.

APIv3

View the Linode APIv3 Documentation.