diff --git a/openapi.yaml b/openapi.yaml index cde42c579..5bf53ac56 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,29371 +1,80621 @@ -openapi: 3.0.1 -info: - version: 4.176.0 - title: Linode API - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - 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 - 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](/docs/api/profile/#personal-access-token-create) endpoint. - - All scopes for the OAuth security model ([defined below](/docs/api/#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/products/tools/api/guides/create-an-oauth-app-with-the-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 specified 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** |
| - - ## 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: - - | 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. | - | HEAD | Returns only the response header information of a GET request | - | OPTIONS | Provides permitted communication options for a command | - - ## Responses - - ### Response Status Codes - - Actions will return one of the 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). | - - ### 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: - - ```Shell - curl -I https://api.linode.com/v4/regions - ``` - - Responses may include the following headers: - - | HEADER | DESCRIPTION | EXAMPLE | - |--------|-------------|---------| - | Access-Control-Allow-Credentials | Responses to credentialed requests are exposed to frontend JavaScript code. | true | - | Access-Control-Allow-Headers | All permissible request headers for this endpoint. | Authorization, Origin, X-Requested-With, Content-Type, Accept, X-Filter | - | Access-Control-Allow-Methods | Permissible HTTP methods for this endpoint | HEAD, GET, OPTIONS, POST, PUT, DELETE | - | Access-Control-Allow-Origin | Indicates origin access permissions. The wildcard character `*` means any origin can access the resource. | * | - | Access-Control-Expose-Headers | Available headers to include in response to cross-origin requests. | X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Status | - | Cache-Control | Controls caching in browsers and shared caches such as CDNs. | private, max-age=60, s-maxage=60 | - | Content-Security-Policy | Controls which resources are allowed to load. By default, resources do not load. | default-src 'none' | - | Content-Type | All responses are in json format. | application/json | - | Content-Warning | A message containing instructions for successful requests that were not able to be completed. | Please contact support for assistance. | - | Retry-After | The remaining time in seconds until the current [rate limit](#rate-limiting) window resets. | 60 | - | Strict-Transport-Security | Enforces HTTPS-only access until the returned time in seconds. | max-age=31536000 | - | Vary | Optional request headers that affected the response content. | Authorization, X-Filter | - | X-Accepted-OAuth-Scopes | Required [scopes](#oauth-reference) for accessing the requested command. | linodes:read_only | - | X-Customer-UUID | A unique identifier for the account owning the the [personal access token](#personal-access-token) that was used for the request. | ABCDEF01-3456-789A-BCDEF0123456789A | - | X-OAuth-Scopes | Allowed [scopes](#oauth-reference) associated with the [personal access token](#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-Limit | The maximum number of permitted requests during the [rate limit](#rate-limiting) window for this endpoint. | 800 | - | X-RateLimit-Remaining | The remaining number of permitted requests in the current [rate limit](#rate-limiting) window. | 798 | - | X-RateLimit-Reset | The time when the current [rate limit](#rate-limiting) window rests in UTC epoch seconds. | 1674747739 | - | X-Spec-Version | The 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](/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 reproducible 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 800 general API requests every two minutes. Additionally, all commands have a rate limit of 400 requests per minute, and all GET commands that return paginated data collections have a rate limit of 200 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) - - Creating Volumes has a dedicated rate limit of 25 requests per minute. That endpoint is: - - * [Volume Create](/docs/api/volumes/#volume-create) - - Listing Images has a dedicated rate limit of 20 requests per minute. That endpoint is: - - * [Images List](/docs/api/images/#images-list) - - `/stats` endpoints have their own dedicated rate limits of 50 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 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](/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. If you exclude any properties from the request, the operation leaves them unchanged. - - **Note:** When updating an account's `country` to "US", you'll get an error if the account's `zip` is not a valid US zip code. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * You can't change the `company` for a parent account. Akamai uses this value to set the name for a child account parent user (proxy user) on any child account. - - * Child account users can't run this operation. These users don't have access to billing-related operations. - operationId: updateAccount - x-linode-cli-action: update - security: - - personalAccessToken: [] - - oauth: - - account:read_write - requestBody: - description: | - Updated contact and billing information. - 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/availability: - x-linode-cli-command: account - get: - tags: - - account - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - summary: Account Availability - description: | - Returns a paginated list of the services available to you, for all Linode regions. - - **Note**: Only authorized Users can access this endpoint. - operationId: getAvailability - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: - - account:read_only - x-linode-cli-action: get-availability - x-linode-grant: read_only - responses: - '200': - description: | - List of regions and the services available in each. - content: - application/json: - schema: - allOf: - - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/AccountAvailability' - - $ref: '#/components/schemas/PaginationEnvelope' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/account/availability \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli account get-availability - /account/availability/{id}: - x-linode-cli-command: account - parameters: - - name: id - in: path - description: The slug for the applicable data center. Run the [GET /regions](/docs/api/regions/#regions-list) operation to view the slug for each data center. - required: true - schema: - type: string - get: - tags: - - account - summary: Region Service Availability - description: | - View the available services for your account in a specific region. - - **Note**: Only authorized users can access this. - operationId: getAccountAvailability - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: - - account:read_only - x-linode-cli-action: get-account-availability - x-linode-grant: read_only - responses: - '200': - description: The services available in the specified region. - content: - application/json: - schema: - $ref: '#/components/schemas/AccountAvailability' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/account/availability/us-east \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli account get-account-availability us-east - /account/betas: - x-linode-cli-command: betas - get: - tags: - - Beta Programs - summary: Enrolled Beta Programs List - operationId: getEnrolledBetaPrograms - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: - - account:read_only - x-linode-cli-action: enrolled - x-linode-grant: unrestricted only - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - Display all enrolled Beta Programs for your Account. Includes inactive as well as active Beta Programs. - - Only unrestricted Users can access this command. - responses: - '200': - description: Returns a paginated list of all enrolled Beta Program objects for the Account. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/BetaProgramEnrolled' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/account/betas \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli betas enrolled - post: - tags: - - Beta Programs - summary: Beta Program Enroll - operationId: enrollBetaProgram - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: - - account:read_write - x-linode-cli-action: enroll - x-linode-grant: unrestricted only - description: | - Enroll your Account in an active Beta Program. - - Only unrestricted Users can access this command. - - To view active Beta Programs, use the Beta Programs List command. - - Active Beta Programs may have a limited number of enrollments. If a Beta Program has reached is maximum number of enrollments, an error is returned even though the request is successful. - - Beta Programs with `"greenlight_only": true` can only be enrolled by Accounts that participate in the [Greenlight](https://www.linode.com/green-light/) program. - requestBody: - description: Updated information for the Managed MySQL Database. - required: true - content: - application/json: - schema: - required: - - id - type: object - description: The Beta Program ID to enroll in for your Account. - properties: - id: - $ref: '#/components/schemas/BetaProgram/properties/id' - responses: - '200': - description: Enrollment request successful. - content: - application/json: - schema: - type: object - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/account/betas \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "id": "example_open" - }' - - lang: CLI - source: > - linode-cli betas enroll --id example_open - /account/betas/{betaId}: - x-linode-cli-command: betas - parameters: - - $ref: '#/components/parameters/betaId' - get: - tags: - - Beta Programs - summary: Enrolled Beta Program View - operationId: getEnrolledBetaProgram - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: - - account:read_only - x-linode-cli-action: enrolled-view - x-linode-grant: unrestricted only - description: | - Display an enrolled Beta Program for your Account. The Beta Program may be inactive. - - Only unrestricted Users can access this command. - responses: - '200': - description: Returns an enrolled Beta Program object for the Account. - content: - application/json: - schema: - $ref: '#/components/schemas/BetaProgramEnrolled' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/account/betas/$betaId \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli betas enrolled-view $betaId - /account/cancel: - x-linode-cli-command: account - post: - x-linode-grant: read_write - tags: - - Account - summary: Account Cancel - description: > - Cancels an active Linode account. Akamai attempts to charge the credit card on file for any remaining - balance. An error occurs if this charge fails. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * A child account user can't cancel a child account. - - * You can't cancel a parent account if it has an active child account. - - * You need to work with your Akamai account team to dissolve any parent-child account relationships before you can fully cancel a child or parent 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 canceled - 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 canceled - 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/child-accounts: - x-linode-cli-command: child-account - get: - x-linode-grant: child_account_access - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - tags: - - Account - summary: Child Account List - description: | - Returns a paginated list of basic information for the child accounts that exist for your parent account. See [Parent and Child Accounts for Akamai Partners](/docs/guides/parent-child-accounts/) for details on these accounts. - - **Note:** This command can only be accessed by an unrestricted parent user, or restricted parent user with the `child_account_access` grant. - operationId: getChildAccounts - x-linode-cli-action: - - list - - ls - security: - - personalAccessToken: [] - - oauth: - - child_account:read_only - responses: - '200': - description: Returns child-level accounts. - content: - application/json: - schema: - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/ChildAccount' - 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/child-accounts - - lang: CLI - source: > - linode-cli child-account list - /account/child-accounts/{euuid}: - x-linode-cli-command: child-account - parameters: - - name: euuid - in: path - description: The child account to look up. You can run the [Child Account List](#child-account-list) operation to find the applicable account and store its `euuid`. - required: true - schema: - type: string - get: - x-linode-grant: child_account_access - tags: - - Account - summary: Child Account View - description: > - View a specific child account based on its `euuid`. See [Parent and Child Accounts for Akamai Partners](/docs/guides/parent-child-accounts/) for details on these accounts. - - **Note:** This command can only be accessed by an unrestricted user, or restricted user with the `child_account_access` grant. - operationId: viewChildAccount - x-linode-cli-action: - - view - security: - - personalAccessToken: [] - - oauth: - - child_account:read_only - responses: - '200': - description: Returns the child-level account for a specified `euuid`. - content: - application/json: - schema: - $ref: '#/components/schemas/ChildAccount' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/account/child-accounts/A1BC2DEF-34GH-567I-J890KLMN12O34P56 - - lang: CLI - source: > - linode-cli child-account view A1BC2DEF-34GH-567I-J890KLMN12O34P56 - /account/child-accounts/{euuid}/token: - x-linode-cli-command: child-account - parameters: - - name: euuid - in: path - description: The child account to look up. You can run the [Child Account List](#child-account-list) operation to find the applicable account and store its `euuid`. - required: true - schema: - type: string - post: - x-linode-grant: child_account_access - tags: - - Account - summary: Proxy User Token Create - description: | - Create a short-lived bearer token for a parent user on a child account, using the `euuid` of that child account. In the context of the API, a parent user on a child account is referred to as a "proxy user." When Akamai provisions your parent-child account environment, a proxy user is automatically set in the child account. It follows a specific naming convention: - - _ - - **Note:** The variables above use only the first 15 and 16 characters of these values, respectively. - - The token lets a parent account run API operations through the proxy user, as if they are a child user in the child account. - - These points apply to the use of this operation: - - * To create a token, a parent account user needs the `child_account_access` grant. This lets them use the proxy user on the child account. You can [view](#users-grants-view) a parent account user to check its `child_account_access` setting. To add this access, you can [update](#users-grants-update) the parent account user. - - * The created token inherits the permissions of the proxy user. It will never have less. - - * The API returns the raw token in the response. You can't get it again, so be sure to store it. - - Example workflow: - - 1. [List child accounts](#child-account-list) and store the `euuid` for the applicable one. - 2. Run this operation and store the `token` that's created for the proxy user. - 3. As a parent account user with access to the proxy user in the child account, use this `token` to authenticate API operations, as if you were a child user. - operationId: createChildAccountToken - x-linode-cli-action: - - create - security: - - personalAccessToken: [] - - oauth: - - child_account:read_write - responses: - '200': - description: Token created successfully. - content: - application/json: - schema: - $ref: '#/components/schemas/ProxyUserToken' - 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/child-accounts/A1BC2DEF-34GH-567I-J890KLMN12O34P56/token - - lang: CLI - source: > - linode-cli child-account create A1BC2DEF-34GH-567I-J890KLMN12O34P56 - /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 canceled. - 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 - - ls - 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. +openapi: "3.0.1" +info: + license: + url: "https://www.apache.org/licenses/LICENSE-2.0.html" + name: "Apache 2.0" + description: "[Read the API documentation](https://techdocs.akamai.com/linode-api/reference/api)." + contact: + email: "support@linode.com" + name: "Linode" + url: "https://linode.com" + version: "4.176.0" + title: "Linode API" +servers: + - + url: "https://api.linode.com" +x-readme: + samples-languages: + - "curl" + - "python" + - "node" +x-akamai: + file-path: "01-account.yaml" + auth-type: "OAUTH" +externalDocs: + url: "https://techdocs.akamai.com/linode-api/reference" + description: "See documentation for Akamai's Linode API" +components: + parameters: + id-path: + in: "path" 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/v4 - - 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. Canceled Maintenance objects are not returned. - - Currently, Linodes are the only entities available for viewing. - operationId: getMaintenance - x-linode-cli-action: maintenance-list - security: - - personalAccessToken: [] - - oauth: [] - 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/v4/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 https://login.linode.com, - 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 - - ls - 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. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * Child account users can't run this operation. These users don't have access to billing-related operations. - 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 the Cloud Manager. See the [Manage Payment Methods](/docs/products/platform/billing/guides/payment-methods/) guide - 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. + x-akamai: + file-path: "parameters/id-path.yaml" + name: "id" + description: "The slug for the applicable data center. Run the [List regions](https://techdocs.akamai.com/linode-api/reference/get-regions) operation to view the slug for each data center." + schema: + type: "string" + payment-id-path: 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 - - rm - 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. + schema: + type: "integer" + in: "path" + x-akamai: + file-path: "parameters/payment-id-path.yaml" + name: "paymentId" + description: "The ID of the Payment to look up." + payment-method-id-path-6078bc7b: 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. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * Child account users can't run this operation. These users don't have access to billing-related operations. - 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. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * Child account users can't run this operation. These users don't have access to billing-related operations. - 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: - properties: - 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 - 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 '{ - "usd": "120.50", - "payment_method_id": 123 - }' \ - https://api.linode.com/v4/account/payments - - lang: CLI - source: > - linode-cli account payment-create \ - --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. + x-akamai: + file-path: "parameters/payment-method-id-path-6078bc7b.yaml" + in: "path" + description: "The ID of the Payment Method to look up." + name: "paymentMethodId" + schema: + type: "integer" + client-id-path: + name: "clientId" + description: "The OAuth Client ID to look up." + in: "path" + x-akamai: + file-path: "parameters/client-id-path.yaml" 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 the Cloud Manager. See [Manage Payment Methods](/docs/products/platform/billing/guides/payment-methods/). - 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 the Cloud Manager. See [Manage Payment Methods](/docs/products/platform/billing/guides/payment-methods/). - 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 needs to be less than 90 days old. - - * You can't already have a Promo Credit on your account. - - * The user making the request needs to be unrestricted. You can use the User Update (/docs/api/account/#user-update) operation to change a user's restricted status. - - * The `promo_code` needs to be valid and unexpired. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * Child account users can't run this operation. These users don't have access to billing-related operations. - 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 - - ls - 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 you need to meet to successfully create a transfer request: - - 1. The account creating the transfer can't have a past due balance or active Terms of Service violation. - - 1. The service needs to be owned by the account that is creating the transfer. - - 1. The service can't be assigned to another Service Transfer that is pending or that's been accepted and is incomplete. - - 1. Linodes can't: - - * be assigned to a NodeBalancer, Firewall, VLAN, VPC, 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 canceled 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 canceled, a transfer cannot be accepted or otherwise acted on in any way. If canceled in error, the transfer must be [created](/docs/api/account/#service-transfer-create) again. - - When canceled, an email notification for the cancellation is sent to the account that created this transfer. Transfers can not be canceled 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 canceled. - 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. For a Longview subscription plan, see [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/guides/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: - x-linode-cli-subtables: - - region_transfers - 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 all users on your account. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - A user can access all or part of an account based on their access status and grants: - - * **Unrestricted access**. These users can access everything on an account. - - * **Restricted access**. These users can only access entities or perform actions they've been given specific grants to. - operationId: getUsers - x-linode-cli-action: - - list - - ls - 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: - allOf: - - $ref: '#/components/schemas/User' - - $ref: '#/components/schemas/UserType' - 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. You determine the new user's account access by setting it to restricted or unrestricted and by defining its grants. After completion, the API sends a confirmation message containing password creation and login instructions to the user's `email` address. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * A parent account user can create new parent account users. - - * A child account can [update](#user-update) the child account parent user (proxy user) to `unrestricted`. This gives the proxy user access to create new child account users. - - * A child account user can create new child account users. - - * You can't create a proxy user. The proxy user in a child account is predefined when you initially provision the parent-child relationship. - 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. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - operationId: getUser - x-linode-cli-action: view - security: - - personalAccessToken: [] - - oauth: - - account:read_only - responses: - '200': - description: The requested User object - content: - application/json: - schema: - items: - allOf: - - $ref: '#/components/schemas/User' - - $ref: '#/components/schemas/UserType' - 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, including its restricted status. When setting a user to `restricted`, the API sets no grants for it. You need to set grants - so that user can access things on the account. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * You can't edit the `username` or `email` values for the child account parent user (proxy user). These are predefined for the proxy user when you initially provision the parent-child relationship. Only a proxy user's `restricted` status can be modified. This can only be done by an unrestricted child account user. - - * A parent account using an unrestricted proxy user in a child account can modify the `username`, `email`, and `restricted` status for an existing child account user. - - * A restricted account user--parent or child--can't change their user to `unrestricted`. - 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: - allOf: - - $ref: '#/components/schemas/User' - - $ref: '#/components/schemas/UserType' - 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 API immediately logs the user out and removes all of its `grants`. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * You can't delete a child account parent user (proxy user). The API returns a 403 error if you target a proxy user with this operation. - - * A parent account using an unrestricted proxy user can use this operation to delete a child account user. - operationId: deleteUser - x-linode-cli-action: - - delete - - rm - 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 an account username you specify. This includes all entities on the account, and the level of access this user has to each of them. - - This doesn't apply to the account owner or the current authenticated user. You can use the [Grants List](/docs/api/profile/#grants-list) operation to view those grants. However, this doesn't show the entities that they *don't* have access to. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - 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 don't need to - include the grant for every entity on the account in this request. Any - that are not included remain unchanged. - - **Note:** This command can only be accessed by account users with *unrestricted* access. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * No child account user can modify the `account_access` grant for the child account parent user (proxy user). - - * An unrestricted child account user can configure all other grants for the proxy user, via `global` object. - - * An unrestricted child account user can enable the `account_access` grant for other child account users. However, enabled child users are still subject to child user restrictions--they can't perform write operations for any billing or account information. - 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, - "add_vpcs": true - }, - "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" - } - ], - "vpc": [ - { - "id": 123, - "permissions": "read_write" - } - ] - }' \ - https://api.linode.com/v4/account/users/example_user/grants - /betas: - x-linode-cli-command: betas - get: - tags: - - Beta Programs - summary: Beta Programs List - operationId: getBetaPrograms - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: [] - x-linode-cli-action: - - list - - ls - x-linode-grant: unrestricted only - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - Display all active Beta Programs. - - Only unrestricted Users can access this command. - responses: - '200': - description: Returns a paginated list of all available Beta Program objects. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/BetaProgram' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/betas \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli betas list - /betas/{betaId}: - x-linode-cli-command: betas - parameters: - - $ref: '#/components/parameters/betaId' - get: - tags: - - Beta Programs - summary: Beta Program View - operationId: getBetaProgram - servers: - - url: https://api.linode.com/v4 - security: - - personalAccessToken: [] - - oauth: [] - x-linode-cli-action: view - x-linode-grant: unrestricted only - description: | - Display information about a Beta Program. This command can be used to access inactive as well as active Beta Programs. - - Only unrestricted Users can access this command. - responses: - '200': - description: Returns a paginated list of all available Beta Program objects. - content: - application/json: - schema: - $ref: '#/components/schemas/BetaProgram' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/betas/$betaId \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli beta view $betaId - /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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 - - ls - x-linode-grant: read_only - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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/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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 and ranges in this list can access the Managed Database. All other sources are blocked. - - * If `0.0.0.0/0` is a value in this list, then all IP addresses can access the Managed Database. - - * 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: - - engine - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 and ranges in this list can access the Managed Database. All other sources are blocked. - - * If `0.0.0.0/0` is a value in this list, then all IP addresses can access the Managed Database. - - * 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' - type: - type: string - description: | - Request re-sizing of your cluster to a Linode Type with more disk space. For example, you could request a Linode Type that uses a higher plan. - - * Needs to be a Linode Type with more disk space than your current Linode. - - * Resizing to a larger Linode Type can accrue additional cost. Review the `price` output in the [Types List](/docs/api/linode-types/#types-list) operation for more information. - - * You can't update the `allow_list` and set a new `type` in the same request. - - * Any active updates to your cluster need to complete before you can request a resize. The reverse is also true: An active resizing needs to complete before you can perform any other update. - example: g6-standard-1 - 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" - ], - "type": "g6-standard-1", - "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 \ - --type g6-standard-1 \ - --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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - Creates a snapshot backup of a Managed MySQL Database. - - Requires `read_write` access to the Database. - - Up to 3 snapshot backups for each Database can be stored at a time. If 3 snapshots have been created for a Database, one must be deleted before another can be made. - - 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. If another backup is in progress, it must complete before a new backup can be initiated. - security: - - personalAccessToken: [] - - oauth: - - databases:read_write - requestBody: - description: Information about the snapshot backup to create. - content: - application/json: - schema: - $ref: '#/components/schemas/DatabaseBackupSnapshot' - 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" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "label": "snapshot1", - "target": "primary" - }' \ - https://api.linode.com/v4/databases/mysql/instances/123/backups/ - - lang: CLI - source: > - linode-cli databases mysql-backup-snapshot 123 \ - --label snapshot1 \ - --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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - Restore a backup to a Managed MySQL Database on your Account. - - Requires `read_write` access to the Database. - - The Database must have an `active`, `degraded`, or `failed` 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 and ranges in this list can access the Managed Database. All other sources are blocked. - - * If `0.0.0.0/0` is a value in this list, then all IP addresses can access the Managed Database. - - * 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: - - engine - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 and ranges in this list can access the Managed Database. All other sources are blocked. - - * If `0.0.0.0/0` is a value in this list, then all IP addresses can access the Managed Database. - - * 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' - type: - type: string - description: | - Request re-sizing of your cluster to a Linode Type with more disk space. For example, you could request a Linode Type that uses a higher plan. - - * Needs to be a Linode Type with more disk space than your current Linode. - - * Resizing to a larger Linode Type can accrue additional cost. Review the `price` output in the [Types List](/docs/api/linode-types/#types-list) operation for more information. - - * You can't update the `allow_list` and set a new `type` in the same request. - - * Any active updates to your cluster need to complete before you can request a resize. The reverse is also true: An active resizing needs to complete before you can perform any other update. - example: g6-standard-1 - 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" - ], - "type": "g6-standard-1", - "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 \ - --type g6-standard-1 \ - --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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - Creates a snapshot backup of a Managed PostgreSQL Database. - - Requires `read_write` access to the Database. - - Up to 3 snapshot backups for each Database can be stored at a time. If 3 snapshots have been created for a Database, one must be deleted before another can be made. - - 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. If another backup is in progress, it must complete before a new backup can be initiated. - security: - - personalAccessToken: [] - - oauth: - - databases:read_write - requestBody: - description: Information about the snapshot backup to create. - content: - application/json: - schema: - $ref: '#/components/schemas/DatabaseBackupSnapshot' - 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" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "label": "snapshot1", - "target": "primary" - }' \ - https://api.linode.com/v4/databases/postgresql/instances/123/backups/ - - lang: CLI - source: > - linode-cli databases postgresql-backup-snapshot 123 \ - --label snapshot1 \ - --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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - Restore a backup to a Managed PostgreSQL Database on your Account. - - Requires `read_write` access to the Database. - - The Database must have an `active`, `degraded`, or `failed` 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 availability 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 - 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: - type: object - properties: - quantity: - x-linode-cli-display: 3 - price: - type: object - 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: | - **This command is currently only available for customers who already have an active Managed Database.** - - 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 - 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: - type: object - properties: - quantity: - x-linode-cli-display: 3 - price: - type: object - 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 - - ls - 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 - - rm - 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-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)$ - minLength: 1 - maxLength: 253 - 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. - - Each domain can have up to 12,000 active records. - 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": "203.0.113.1", - "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 203.0.113.1 \ - --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. + schema: + type: "string" + username-path: + schema: + type: "string" required: true - schema: - type: integer - - name: recordId - in: path - description: The ID of the Record you are accessing. + x-akamai: + file-path: "parameters/username-path.yaml" + in: "path" + description: "The username to look up." + name: "username" + event-id-path-39255fcf: + schema: + type: "integer" + description: "The ID of the Event." + name: "eventId" 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: - type: object - description: A Domain Record Update request object. - properties: - name: - $ref: '#/components/schemas/DomainRecord/properties/name' - target: - $ref: '#/components/schemas/DomainRecord/properties/target' - priority: - $ref: '#/components/schemas/DomainRecord/properties/priority' - weight: - $ref: '#/components/schemas/DomainRecord/properties/weight' - port: - $ref: '#/components/schemas/DomainRecord/properties/port' - service: - $ref: '#/components/schemas/DomainRecord/properties/service' - protocol: - $ref: '#/components/schemas/DomainRecord/properties/protocol' - ttl_sec: - $ref: '#/components/schemas/DomainRecord/properties/ttl_sec' - tag: - $ref: '#/components/schemas/DomainRecord/properties/tag' - 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 '{ - "name": "test", - "target": "203.0.113.1", - "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 \ - --name test \ - --target 203.0.113.1 \ - --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 - - ls - 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. - cloud_init: - type: boolean - description: Whether this Image supports cloud-init. - example: true - 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 canceled 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. - cloud_init: - type: boolean - description: Whether the uploaded Image supports cloud-init. - example: true - 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. + x-akamai: + file-path: "parameters/event-id-path-39255fcf.yaml" + in: "path" + page-size: + schema: + default: 100 + minimum: 25 + type: "integer" + maximum: 500 + in: "query" + x-akamai: + file-path: "parameters/page-size.yaml" + name: "page_size" + description: "The number of items to return per page." + token-path-faf66b58: + in: "path" + x-akamai: + file-path: "parameters/token-path-faf66b58.yaml" + name: "token" + description: "The UUID of the Entity Transfer." + schema: + format: "uuid" + type: "string" 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 - - rm - 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 - - ls - 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 our guide on [Running a Mail Server](/docs/guides/running-a-mail-server/). - - **Important**: You must be an unrestricted User in order to add or modify tags on Linodes. - - 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 cloud-init with [Metadata](/docs/products/compute/compute-instances/guides/metadata/). - * Automate system configuration and software installation by providing a base-64 encoded [cloud-config](/docs/products/compute/compute-instances/guides/metadata-cloud-config/) file. - * Requires a compatible Image. You can determine compatible Images by checking for `cloud-init` under `capabilities` when using Images List ([GET /images](/docs/api/images/#images-list)). - * Requires a compatible Region. You can determine compatible Regions by checking for `Metadata` under `capabilities` when using Regions List ([GET /regions](/docs/api/regions/#regions-list)). - - * 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/products/networking/vlans/get-started/). - - * 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. - 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: - - authorized_users - - 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' - firewall_id: - type: integer - description: The `id` of the Firewall to attach this Linode to upon creation. - 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/ubuntu22.04", - "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" - }, - { - "purpose": "vpc", - "primary": false, - "label": "", - "ipam_address": "", - "subnet_id": 101, - "ipv4": { - "vpc": "10.0.1.2", - "nat_1_1": "any" - } - } - ], - "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", - "metadata": { - "user_data": "I2Nsb3VkLWNvbmZpZw==" - }, - "firewall_id": 9000 - }' \ - 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" \ - --metadata.user_data "I2Nsb3VkLWNvbmZpZw==" \ - --firewall_id 9000 - /linode/instances/{linodeId}: - parameters: - - name: linodeId - in: path - description: ID of the Linode to look up + event-id-path-214cd042: + x-akamai: + file-path: "parameters/event-id-path-214cd042.yaml" + in: "path" + description: "The ID of the Event to designate as seen." + name: "eventId" 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. - * Detaches any Volumes associated with the Linode. - * 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 - - rm - 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. + schema: + type: "integer" + client-id-path-ecf807fb: + x-akamai: + file-path: "parameters/client-id-path-ecf807fb.yaml" + in: "path" + description: "The OAuth Client ID to look up." + name: "clientId" + schema: + type: "string" 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. + invoice-id-path: + schema: + type: "integer" + in: "path" 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 canceled 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. + x-akamai: + file-path: "parameters/invoice-id-path.yaml" + name: "invoiceId" + description: "The ID of the Invoice." + api-version-path: + schema: + enum: + - "v4" + - "v4beta" + default: "v4" + type: "string" + in: "path" + x-akamai: + file-path: "parameters/api-version-path.yaml" 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. + name: "apiVersion" + description: "Call either the `v4` URL, or `v4beta` for operations still in Beta." + payment-method-id-path-fb39a844: + schema: + type: "integer" + name: "paymentMethodId" + description: "The ID of the Payment Method to make default." + in: "path" required: true - schema: - type: integer - - name: backupId - in: path - description: The ID of the Backup to look up. + x-akamai: + file-path: "parameters/payment-method-id-path-fb39a844.yaml" + event-id-path-625aa248: + schema: + type: "integer" + in: "path" 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. + x-akamai: + file-path: "parameters/event-id-path-625aa248.yaml" + name: "eventId" + description: "The ID of the Event to designate as read." + beta-id: + schema: + type: "string" + x-akamai: + file-path: "parameters/beta-id.yaml" required: true - schema: - type: integer - - name: backupId - in: path - description: The ID of the Backup to restore. + in: "path" + description: "The ID of the Beta Program." + name: "betaId" + page-offset: + in: "query" + x-akamai: + file-path: "parameters/page-offset.yaml" + required: false + name: "page" + description: "The page of a collection to return." + schema: + default: 1 + type: "integer" + minimum: 1 + token-path-f857f5a2: + schema: + format: "uuid" + type: "string" + name: "token" + description: "The UUID of the Service Transfer." + in: "path" + x-akamai: + file-path: "parameters/token-path-f857f5a2.yaml" 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. - - The following conditions apply: - * Backups may not be restored across Regions. - * Only successfully completed Backups that are not undergoing maintenance can be restored. - * The Linode that the Backup is being restored to must not itself be in the process of creating a Backup. - - {{< note type="warning" title="Warning: UUID Collisions">}} - When you restore a backup, the restored disk is assigned the same [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) as the original disk. In most cases, this is acceptable and does not cause issues. However, if you attempt to mount both the original disk and the corresponding restore disk at the same time (by assigning them both to devices in your Configuration Profile's **Block Device Assignment**), you will encounter a UUID "collision". - - When this happens, the system selects, and mounts, only one of the disks at random. This is due to both disks sharing the same UUID, and your instance *may fail to boot* since it will not be clear which disk is root. If your system does boot, you will not see any immediate indication if you are booted into the restored disk or the original disk, and you will be unable to access both disks at the same time. - - To avoid this, we recommend only restoring a backup to the same Compute Instance if you do not intend on mounting them at the same time or are comfortable modifying UUIDs. If you need access to files on both the original disk and the restored disk simultaneously (such as needing to copy files between them), we suggest either restoring the backup to a separate Compute Instance or [creating](/docs/api/linode-instances/#linode-create) a new Compute Instance with the desired `backup_id`. - - To learn more about block device assignments and viewing your disks' UUIDs, see our guide on [Configuration Profiles](/docs/products/compute/compute-instances/guides/configuration-profiles/#block-device-assignment). - {{< /note >}} - 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. + login-id-path: + in: "path" + x-akamai: + file-path: "parameters/login-id-path.yaml" + name: "loginId" + description: "The ID of the login object to access." + schema: + type: "integer" 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. + eeuid: + description: "The child account to look up. You can run the [List child accounts](https://techdocs.akamai.com/linode-api/reference/get-child-accounts) operation to find the applicable account and store its `euuid`." + name: "euuid" 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. - - Linodes utilizing Metadata (`"has_user_data": true`) must be cloned to a new Linode with `metadata.user_data` included with the clone request. - - `vpc` details - - - If the Linode you are cloning has a `vpc` purpose Interface on its active Configuration Profile that includes a 1:1 NAT, the resulting clone is configured with an `any` 1:1 NAT. - - See the [VPC documentation](/docs/products/networking/vpc/#technical-specifications) guide for its specifications and limitations. - - `vlan` details - - - Only Next Generation Network (NGN) data centers support VLANs. If a VLAN is attached to your Linode and you attempt clone it to a non-NGN data center, the cloning will not initiate. If a Linode cannot be cloned because of an incompatibility, you will be prompted to select a different data center or contact support. - - See the [VLANs Overview](/docs/products/networking/vlans/#technical-specifications) guide to view additional specifications and limitations. - 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 - [GET /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 - private_ip: - type: boolean - description: > - If true, the created Linode will have private networking enabled and assigned a private IPv4 address. - - * Can only be provided when cloning to a new Linode. - example: true - metadata: - $ref: '#/components/schemas/LinodeRequest/properties/metadata' - 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], - "private_ip": true, - "metadata": { - "user_data": "I2Nsb3VkLWNvbmZpZw==" - } - }' \ - 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 \ - --private_ip true \ - --metadata.user_data I2Nsb3VkLWNvbmZpZw== - /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: - - $ref: '#/components/parameters/linodeId' - - $ref: '#/components/parameters/configId' - 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}/configs/{configId}/interfaces: - x-linode-cli-command: linodes - parameters: - - $ref: '#/components/parameters/linodeId' - - $ref: '#/components/parameters/configId' - get: - tags: - - Linode Instances - x-linode-grant: read_only - servers: - - url: https://api.linode.com/v4 - summary: Configuration Profile Interfaces List - description: | - Returns an ordered array of all Interfaces associated with this Configuration Profile. - * The User accessing this command must have at least `read_only` grants to the Linode. - operationId: getLinodeConfigInterfaces - x-linode-cli-action: - - config-interfaces-list - - config-interfaces-ls - security: - - personalAccessToken: [] - - oauth: - - linodes:read_only - responses: - '200': - description: An ordered array of Interface objects. - content: - application/json: - schema: - $ref: '#/components/schemas/LinodeConfigInterfaces' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/linode/instances/$linodeId/configs/$configId/interfaces \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli linodes config-interfaces-list $linodeId $configId - post: - x-linode-grant: read_write - summary: Configuration Profile Interface Add - servers: - - url: https://api.linode.com/v4 - description: | - Creates and appends a single Interface to the end of the `interfaces` array for an existing Configuration Profile. - * The User accessing this command must have `read_write` grants to the Linode. - * A successful request triggers a `linode_config_update` event. - * If the new Interface is added with `"primary": true`, then any existing primary Interface is changed to `"primary": false`. - - Reboot the Linode with this Configuration Profile to activate an Interface that was added with this command. - tags: - - Linode Instances - operationId: addLinodeConfigInterface - x-linode-cli-action: config-interface-add - security: - - personalAccessToken: [] - - oauth: - - linodes:read_write - requestBody: - description: The Interface to add to the Configuration Profile. - required: true - content: - application/json: - schema: - allOf: - - required: - - purpose - - $ref: '#/components/schemas/LinodeConfigInterface' - responses: - '200': - description: Interface successfully added. - content: - application/json: - schema: - $ref: '#/components/schemas/LinodeConfigInterface' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/linode/instances/$linodeId/configs/$configId/interfaces \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "purpose": "vpc", - "primary": false, - "label": "", - "ipam_address": "", - "subnet_id": 101, - "ipv4": { - "vpc": "10.0.1.2", - "nat_1_1": "203.0.113.2" - } - }' - - lang: CLI - source: > - linode-cli linodes config-interface-add $linodeId $configId \ - --purpose vpc \ - --primary false \ - --subnet_id 101 \ - --ipv4.vpc "10.0.1.2" \ - --ipv4.nat_1_1 "203.0.113.2" - /linode/instances/{linodeId}/configs/{configId}/interfaces/{interfaceId}: - x-linode-cli-command: linodes - parameters: - - $ref: '#/components/parameters/linodeId' - - $ref: '#/components/parameters/configId' - - name: interfaceId - in: path - description: The `id` of the Linode Configuration Profile Interface. - required: true - schema: - type: integer - delete: - summary: Configuration Profile Interface Delete - servers: - - url: https://api.linode.com/v4 - description: | - Deletes an Interface from the Configuration Profile. - - * The User accessing this command must have `read_write` grants to the Linode. - * A successful request triggers a `linode_config_update` event. - * Active Interfaces cannot be deleted. The associated Linode must first be shut down (or restarted using another Configuration Profile) before such Interfaces can be deleted from a Configuration Profile. - x-linode-grant: read_write - tags: - - Linode Instances - operationId: deleteLinodeConfigInterface - x-linode-cli-action: config-interface-delete - security: - - personalAccessToken: [] - - oauth: - - linodes:read_write - responses: - '200': - description: Interface 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/$linodeId/configs/$configId/interfaces/$interfaceId - - lang: CLI - source: > - linode-cli linodes config-delete $linodeId $configId $interfaceId - get: - tags: - - Linode Instances - x-linode-grant: read_only - servers: - - url: https://api.linode.com/v4 - summary: Configuration Profile Interface View - description: | - Returns a single Configuration Profile Interface. - * The User accessing this command must have at least `read_only` grants to the Linode. - operationId: getLinodeConfigInterface - x-linode-cli-action: - - config-interface-view - security: - - personalAccessToken: [] - - oauth: - - linodes:read_only - responses: - '200': - description: An Interface object. - content: - application/json: - schema: - $ref: '#/components/schemas/LinodeConfigInterface' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/linode/instances/$linodeId/configs/$configId/interfaces/$interfaceId \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli linodes config-interface-view $linodeId $configId $interfaceId - put: - x-linode-grant: read_write - summary: Configuration Profile Interface Update - servers: - - url: https://api.linode.com/v4 - description: | - Updates a `vpc` or `public` purpose Interface for this Configuration Profile. - * The User accessing this command must have `read_write` grants to the Linode. - * A successful request triggers a `linode_config_update` event. - * The Interface `purpose` cannot be updated with this command. - * VPC Subnets cannot be updated on an Interface. A new `vpc` purpose Interface must be created to assign a different Subnet to a Configuration Profile. - * Only `primary` can be updated for `public` purpose Interfaces. - * This command not currently allowed for `vlan` purpose Interfaces. - tags: - - Linode Instances - operationId: updateLinodeConfigInterface - x-linode-cli-action: config-interface-update - security: - - personalAccessToken: [] - - oauth: - - linodes:read_write - requestBody: - description: The updated Interface. - required: true - content: - application/json: - schema: - type: object - description: Linode Configuration Interface Update request object. - properties: - primary: - $ref: '#/components/schemas/LinodeConfigInterface/properties/primary' - ipv4: - $ref: '#/components/schemas/LinodeConfigInterface/properties/ipv4' - ip_ranges: - $ref: '#/components/schemas/LinodeConfigInterface/properties/ip_ranges' - # ipv6: - # $ref: '#/components/schemas/LinodeConfigInterface/properties/ipv6' - responses: - '200': - description: Interface successfully updated. - content: - application/json: - schema: - $ref: '#/components/schemas/LinodeConfigInterface' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/linode/instances/$linodeId/configs/$configId/interfaces/$interfaceId \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X PUT -d '{ - "primary": true, - "ipv4": { - "vpc": "10.0.1.2", - "nat_1_1": "203.0.113.2" - } - }' - - lang: CLI - source: > - linode-cli linodes config-interface-update $linodeId $configId $interfaceId \ - --primary true \ - --ipv4.vpc "10.0.1.2" \ - --ipv4.nat_1_1 "203.0.113.2" - /linode/instances/{linodeId}/configs/{configId}/interfaces/order: - x-linode-cli-command: linodes - parameters: - - $ref: '#/components/parameters/linodeId' - - $ref: '#/components/parameters/configId' - post: - x-linode-grant: read_write - summary: Configuration Profile Interfaces Order - servers: - - url: https://api.linode.com/v4 - description: | - Reorders the existing Interfaces of a Configuration Profile. - * The User accessing this command must have `read_write` grants to the Linode. - tags: - - Linode Instances - operationId: orderLinodeConfigInterfaces - x-linode-cli-action: config-interfaces-order - security: - - personalAccessToken: [] - - oauth: - - linodes:read_write - requestBody: - description: The desired Interface order for the Configuration Profile. - required: true - content: - application/json: - schema: - type: object - description: Linode Configuration Interfaces Order request object. - required: - - ids - properties: - ids: - type: array - description: | - An ordered array of existing Configuration Profile Interface `id`s. - - * All current Interface `id`s must be present in the array. - * If the Configuration Profile contains Interfaces and is active on the Linode, the Linode must first be shut down prior to running this command. - * Reordering takes effect after rebooting the Linode with this Configuration Profile. - - The position in the array determines which of the Linode's network Interfaces is configured: - - * First [0]: eth0 - * Second [1]: eth1 - * Third [2]: eth2 - items: - $ref: '#/components/schemas/LinodeConfigInterface/properties/id' - responses: - '200': - description: Interfaces successfully reordered. - content: - application/json: - schema: - type: object - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/linode/instances/$linodeId/configs/$configId/interfaces/order \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "ids": [ - 101, - 102, - 103 - ] - }' - - lang: CLI - source: > - linode-cli linodes config-interfaces-order $linodeId $configId \ - --ids 101 --ids 102 --ids 103 - /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: - properties: - label: - $ref: '#/components/schemas/Disk/properties/label' - 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 access. - 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 assigned to 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 assigned to 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. - - **Note:** If the target Linode has several configuration profiles that include a Virtual Private Cloud (VPC) interface, address information for all of VPCs will be listed in the response. - 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: - x-linode-cli-subtables: - - ipv4.public - - ipv4.private - - ipv4.shared - - ipv4.reserved - - ipv4.vpc - - ipv6.link_local - - ipv6.slaac - - ipv6.global - 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 - vpc: - type: array - readOnly: true - items: - $ref: '#/components/schemas/IPAddressesVPC' - description: > - A list of Virtual Private Cloud (VPC)-specific addresses or ranges for the Linode. - reserved: - type: array - readOnly: true - items: - $ref: '#/components/schemas/IPAddress' - description: > - A list of reserved IP Address objects belonging to this Linode. - shared: - type: array - readOnly: true - items: - $ref: '#/components/schemas/IPAddress' - description: > - A list of shared IP Address objects assigned 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: - type: array - items: - $ref: '#/components/schemas/IPv6Range' - description: | - A list of IPv6 range objects assigned to this Linode. - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/linode/instances/123/ips - - lang: CLI - source: > - linode-cli linodes ips-list 123 - 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. - required: true - schema: - type: integer - - name: address - in: path - description: The IP address. - 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 "Authorization: Bearer $TOKEN" \ - 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 RDNS Update - description: | - Updates the reverse DNS (RDNS) for a Linode's IP Address. This may be done for both IPv4 and IPv6 addresses. - - Setting the RDNS to `null` for a public IPv4 address, resets it to the default "ip.linodeusercontent.com" RDNS value. - 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: - 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. - nullable: true - example: test.example.org - 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/203.0.113.1 - - lang: CLI - source: > - linode-cli linodes ip-update 123 \ - 203.0.113.1 \ - --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, or if the address has a 1:1 NAT with an active VPC Subnet 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. - - Due to the extensive list of available kernels, please keep [pagination](/docs/api/#pagination) controls in mind when managing responses to this command. - operationId: getKernels - x-linode-cli-action: - - list - - ls - 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). See our [Pricing Page](https://www.linode.com/pricing/) for Region-specific pricing, which applies after migration is complete. 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. - - `vpc` details - - - Cross DC migrations are not allowed for Linodes that have a `vpc` purpose Configuration Profile Interface. Host migrations within the same DC are permitted. - - See the [VPC documentation](/docs/products/networking/vpc/#technical-specifications) guide for its specifications and limitations. - - `vlan` details - - - 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 or cloned because of an incompatibility, you will be prompted to select a different data center or contact support. - - 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. - - See the [VLANs Overview](/docs/products/networking/vlans/#technical-specifications) guide to view additional specifications and limitations. - 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 - type: - type: string - enum: - - warm - - cold - description: | - Type of migration used in moving to a new host or Linode type. - - `warm`: the Linode will not power down until the migration is complete. - Warm migrations are not available for DC migrations. - - `cold`: the Linode will be powered down and migrated. When the migration - is complete, the Linode will be powered on. - example: warm - default: cold - 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. - * Linodes utilizing Metadata (`"has_user_data": true`) should include `metadata.user_data` in the rebuild request to continue using the service. - - You also have the option to resize the Linode to a different plan by including the `type` parameter with your request. Note that resizing involves migrating the Linode to a new hardware host, while rebuilding without resizing maintains the same hardware host. Resizing also requires significantly more time for completion of this command. The following additional conditions apply: - - * 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: 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' - - type: object - properties: - type: - type: string - description: > - The ID of the [Linode Type](/docs/api/linode-types/#types-list) to resize to with this request. - example: g6-standard-2 - 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" - }, - "type": "g6-standard-2", - "metadata": { - "user_data": "I2Nsb3VkLWNvbmZpZw==" - } - }' \ - 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"}' \ - --type "g6-standard-2" \ - --metadata.userdata "I2Nsb3VkLWNvbmZpZw==" - /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. - - You can also resize a Linode when using the [Linode Rebuild](/docs/api/linode-instances/#linode-rebuild) command. - 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 - migration_type: - type: string - enum: - - warm - - cold - description: | - Type of migration used in moving to a new host or Linode type. - - `warm`: the Linode will not power down until the migration is complete. - Warm migrations are not available for DC migrations. - - `cold`: the Linode will be powered down and migrated. When the migration - is complete, the Linode will be powered on. - example: warm - default: cold - 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 + x-akamai: + file-path: "parameters/eeuid.yaml" + in: "path" + schema: + type: "string" + schemas: + started: + format: "date-time" + x-linode-cli-display: 5 + x-akamai: + labels: + - "Filterable" + type: "string" + description: "__Filterable__, __Read-only__ The start date-time of the Beta Program." + readOnly: true + example: "2023-07-11T00:00:00" + x-linode-filterable: true + promotion: + additionalProperties: false + properties: + service_type: + x-linode-cli-display: 1 + type: "string" + description: "The service to which this promotion applies." + example: "all" + enum: + - "all" + - "backup" + - "blockstorage" + - "db_mysql" + - "ip_v4" + - "linode" + - "linode_disk" + - "linode_memory" + - "loadbalancer" + - "longview" + - "managed" + - "nodebalancer" + - "objectstorage" + - "placement_group" + - "transfer_tx" + this_month_credit_remaining: + example: "10.00" + description: "The amount of credit left for this month for this promotion." + type: "string" + x-linode-cli-display: 4 + expire_dt: + description: "When this promotion's credits expire." + type: "string" + x-linode-cli-display: 2 + example: "2018-01-31T23:59:59" + summary: + example: "$10 off your Linode a month!" + type: "string" + description: "Short details of this promotion." + x-linode-cli-display: 10 + description: + description: "A detailed description of this promotion." + type: "string" + example: "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends." + credit_monthly_cap: + description: "The amount available to spend per month." + type: "string" + x-linode-cli-display: 5 + example: "10.00" + credit_remaining: + type: "string" + description: "The total amount of credit left for this promotion." + x-linode-cli-display: 3 + example: "50.00" + image_url: + example: "https://linode.com/10_a_month_promotion.svg" + description: "The location of an image for this promotion." + type: "string" + x-akamai: + file-path: "schemas/promotion.yaml" + description: "__Read-only__ 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.\n\nSimply put, a promotion offers a certain amount of credit month, until either the expiration date is passed, or until the total promotional credit is used, whichever comes first." + type: "object" + readOnly: true + added-get-users-200: + type: "object" + properties: + pages: + type: "integer" + description: "__Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination)." + readOnly: true + example: 1 + page: + description: "__Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination)." + type: "integer" + readOnly: true + example: 1 + data: + type: "array" + items: + allOf: + - + x-akamai: + file-path: "schemas/user.yaml" + properties: + ssh_keys: + items: + type: "string" + type: "array" + description: "__Read-only__ A list of SSH Key labels added by this User.\n\nUsers can add keys with the [Add an SSH key](https://techdocs.akamai.com/linode-api/reference/post-add-ssh-key) operation.\n\nThese keys are deployed when this User is included in the `authorized_users` field of the following requests:\n\n- [Create a Linode](https://techdocs.akamai.com/linode-api/reference/post-linode-instance)\n- [Rebuild a Linode](https://techdocs.akamai.com/linode-api/reference/post-rebuild-linode-instance)\n- [Create a disk](https://techdocs.akamai.com/linode-api/reference/post-add-linode-disk)" readOnly: true - billable: - type: integer - description: > - The amount of network transfer this Linode has used, in GB, past your monthly quota. - example: 0 + example: + - "home-pc" + - "laptop" + email: + example: "example_user@linode.com" + x-linode-cli-display: 2 + format: "email" + type: "string" + 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." + restricted: + x-linode-cli-display: 3 + description: "If true, the User must be granted access to perform actions or access entities on this Account. Run [List a user's grants](https://techdocs.akamai.com/linode-api/reference/get-user-grants) for details on how to configure grants for a restricted User." + type: "boolean" + example: true + password_created: 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 + example: "2018-01-01T01:01:01" + format: "date-time" + type: "string" + description: "__Read-only__ The date and time when this User's current password was created.\n\nUser passwords are first created during the Account sign-up process, and updated using the [Reset Password](https://login.linode.com/forgot/password) webpage.\n\n`null` if this User has not created a password yet." + nullable: true + tfa_enabled: + type: "boolean" + description: "__Read-only__ A boolean value indicating if the User has Two Factor Authentication (TFA) enabled. Run the [Create a two factor secret](https://techdocs.akamai.com/linode-api/reference/post-tfa-enable) operation to enable TFA." 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 + example: true + username: + description: "__Filterable__ 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)." + type: "string" + x-linode-cli-display: 1 + x-akamai: + labels: + - "Filterable" + minLength: 3 + pattern: "^[a-zA-Z0-9]((?![_-]{2,})[a-zA-Z0-9-_])+[a-zA-Z0-9]$" + maxLength: 32 + example: "example_user" + x-linode-filterable: true + last_login: 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 + additionalProperties: false + description: "__Read-only__ Information for the most recent login attempt for this User.\n\n`null` if no login attempts have been made since creation of this User.\n\nRun the [List user logins](https://techdocs.akamai.com/linode-api/reference/get-account-logins) operation for additional login information." + type: "object" + nullable: true + properties: + status: + readOnly: true + enum: + - "successful" + - "failed" + example: "successful" + description: "__Read-only__ The result of the most recent login attempt for this User." + type: "string" + login_datetime: + example: "2018-01-01T01:01:01" + readOnly: true + type: "string" + description: "__Read-only__ The date and time of this User's most recent login attempt." + format: "date-time" + verified_phone_number: 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 documentation](/docs/products/tools/stackscripts/). - operationId: getStackScripts - x-linode-cli-action: - - list - - ls - 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 - - rm - 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: - x-linode-cli-subtables: - - region_prices - 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.27", - "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.27 \ - --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.27" - }' \ - 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.27 \ - --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: - 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/clusters/{clusterId}/regenerate: - parameters: - - name: clusterId - in: path - description: ID of the target Kubernetes cluster. - required: true - schema: - type: integer - x-linode-cli-command: lke - post: - operationId: postLKEClusterRegenerate - x-linode-cli-action: regenerate - security: - - personalAccessToken: [] - - oauth: - - lke:read_write - tags: - - Linode Kubernetes Engine (LKE) - summary: Kubernetes Cluster Regenerate - description: | - Regenerate the Kubeconfig file and/or the service account token for a Cluster. - - This is a helper command that allows performing both the [Kubeconfig Delete](#kubeconfig-delete) and the [Service Token Delete](#service-token-delete) actions with a single request. - - When using this command, at least one of `kubeconfig` or `servicetoken` is required. - - **Note**: When regenerating a service account token, the Cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High Availability Clusters should not experience any disruption, while standard Clusters may experience brief control plane downtime while components are restarted. - requestBody: - description: The Kubernetes Cluster Regenerate request object. - content: - application/json: - schema: - properties: - kubeconfig: - type: boolean - default: false - example: true - description: | - Whether to delete and regenerate the Kubeconfig file for this Cluster. - servicetoken: - type: boolean - default: false - example: true - description: | - Whether to delete and regenerate the service access token for this Cluster. - responses: - '200': - description: Regenerate 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 '{ - "kubeconfig": true, - "servicetoken": true - }' \ - https://api.linode.com/v4/lke/clusters/12345/regenerate - - lang: CLI - source: > - linode-cli lke regenerate 12345 \ - --kubeconfig true \ - --servicetoken true - /lke/clusters/{clusterId}/servicetoken: - parameters: - - name: clusterId - in: path - description: ID of the target Kubernetes cluster. - required: true - schema: - type: integer - x-linode-cli-command: lke - delete: - operationId: postLKECServiceTokenDelete - x-linode-cli-action: service-token-delete - security: - - personalAccessToken: [] - - oauth: - - lke:read_write - tags: - - Linode Kubernetes Engine (LKE) - summary: Service Token Delete - description: | - Delete and regenerate the service account token for a Cluster. - - **Note**: When regenerating a service account token, the Cluster's control plane components and Linode CSI drivers are also restarted and configured with the new token. High Availability Clusters should not experience any disruption, while standard Clusters may experience brief control plane downtime while components are restarted. - responses: - '200': - description: Service token 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/servicetoken - - lang: CLI - source: > - linode-cli lke service-token-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.27 - - lang: CLI - source: > - linode-cli lke version-view 1.27 - /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 - - ls - 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 - - rm - 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/products/services/managed/get-started/#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 + example: "+5555555555" + format: "phone" + type: "string" + description: "__Read-only__ The phone number verified for this User Profile with the [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation.\n\n`null` if this User Profile has no verified phone number." + nullable: true + 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." + additionalProperties: false + - + additionalProperties: false + description: "The type of user on an account. Mostly applies to the use of the parent and child accounts for Akamai partners functionality." + type: "object" + x-akamai: + file-path: "schemas/user-type.yaml" + properties: + user_type: 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": "203.0.113.1", - "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 203.0.113.1 - /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. - - **Note**: Use the `skip_ipv6_rdns` query string to improve performance if your application frequently accesses this command and doesn't require IPv6 RDNS data. - operationId: getIPs - x-linode-cli-action: ips-list - security: - - personalAccessToken: [] - - oauth: - - ips:read_only - parameters: - - name: skip_ipv6_rdns - in: query - description: | - When `true`, the `rdns` property for any `ipv6` type addresses always returns `null` regardless of whether RDNS data exists for the address. - schema: - type: boolean + example: "parent" + enum: + - "parent" + - "child" + - "proxy" + - "default" + description: "__Read-only__ If the user belongs to a [parent or child account](https://www.linode.com/docs/guides/parent-child-accounts/) relationship, this defines the user type in the respective account. Possible values include:\n\n- `parent`. This is a user in an Akamai partner account. Akamai partners have a contractural relationship with their end customers, to sell Akamai services. This user can either have full access (a parent account admin user) or limited access. Limited users don't have access to manage child accounts, but they can be granted this access by an admin user.\n\n- `child`. This is an Akamai partner's end customer user, in a child account. A child user can have either full or limited access. Full access lets the user manage other child users and the proxy user in a child account.\n\n- `proxy`. This is a user on a child account that gives parent account users access to that child account. A parent account user with the `child_account_access` grant can [Create a proxy user token](https://techdocs.akamai.com/linode-api/reference/post-child-account-token) from the parent account. The parent user can use this token to run API operations from the child account, as if they were a child user.\n\n- `default`. This applies to all regular, non-parent-child account users." + type: "string" + results: + example: 1 + readOnly: true + type: "integer" + description: "__Read-only__ The total number of results." + x-akamai: + file-path: "schemas/added-get-users-200.yaml" + additionalProperties: false + invoice: + description: "Account Invoice object." + type: "object" + properties: + date: + readOnly: true + example: "2018-01-01T00:01:01" + x-linode-filterable: true + x-linode-cli-display: 2 + format: "date-time" + x-akamai: + labels: + - "Filterable" + type: "string" + description: "__Filterable__, __Read-only__ When this Invoice was generated." + id: + description: "__Read-only__ The Invoice's unique ID." + type: "integer" + x-linode-cli-display: 1 + example: 123 + readOnly: true + tax_summary: + description: "__Read-only__ The amount of tax broken down into subtotals by source." + type: "array" + items: + properties: + name: + description: "The source of this tax subtotal." + type: "string" + example: "PA STATE TAX" + tax: + description: "The amount of tax subtotal attributable to this source." + type: "number" + example: 12.25 + type: "object" + additionalProperties: false + readOnly: true + tax: + x-linode-cli-display: 5 + type: "number" + description: "__Read-only__ The amount of tax levied on the Invoice in US Dollars." + readOnly: true + example: 12.25 + billing_source: + x-akamai: + labels: + - "Filterable" + x-linode-cli-display: 3.5 + type: "string" + description: "__Filterable__, __Read-only__ `akamai`: This Invoice was generated according to the terms of an agreement between the customer and Akamai.\n\n`linode`: This Invoice was generated according to the default terms, prices, and discounts." + readOnly: true + x-linode-filterable: true + enum: + - "akamai" + - "linode" + example: "linode" + total: + x-linode-cli-display: 6 + x-akamai: + labels: + - "Filterable" + type: "number" + description: "__Filterable__, __Read-only__ The amount of the Invoice after taxes in US Dollars." + readOnly: true + example: 132.5 + x-linode-filterable: true + label: + example: "Invoice" + x-linode-filterable: true + readOnly: true + type: "string" + description: "__Filterable__, __Read-only__ The Invoice's display label." + x-linode-cli-display: 3 + x-akamai: + labels: + - "Filterable" + subtotal: + readOnly: true + example: 120.25 + x-linode-cli-display: 4 + description: "__Read-only__ The amount of the Invoice before taxes in US Dollars." + type: "number" + x-akamai: + file-path: "schemas/invoice.yaml" + additionalProperties: false + child-account: + additionalProperties: false + x-akamai: + file-path: "schemas/child-account.yaml" + properties: + zip: + x-linode-filterable: true + example: "92111-1234" + x-akamai: + labels: + - "Filterable" + type: "string" + description: "__Filterable__ The zip code of this Account's billing address. The following restrictions apply:\n\n- Can only contain ASCII letters, numbers, and hyphens (`-`).\n- Can't contain more than 9 letter or number characters." + address_2: + type: "string" + description: "__Filterable__ Second line of this child account's billing address, if applicable." + x-akamai: + labels: + - "Filterable" + x-linode-filterable: true + example: "Suite A" + maxLength: 64 + capabilities: + readOnly: true + example: + - "Linodes" + - "NodeBalancers" + - "Block Storage" + - "Object Storage" + items: + type: "string" + type: "array" + description: "__Read-only__ A list of the capabilities the child account supports." + first_name: + example: "John" + maxLength: 50 + x-linode-filterable: true + type: "string" + description: "__Filterable__ The first name of the owner of this child account. It can't include any of these characters: `<` `>` `(` `)` `\"` `=`." + x-linode-cli-display: 1 + x-akamai: + labels: + - "Filterable" + active_since: + readOnly: true + example: "2018-01-01T00:01:01" + format: "date-time" + description: "__Read-only__ The activation date and time for the child account." + type: "string" + balance: + description: "__Read-only__ This child account's balance, in US dollars." + type: "number" + x-linode-cli-display: 4 + example: 200 + readOnly: true + city: + example: "San Diego" + maxLength: 24 + x-linode-filterable: true + x-akamai: + labels: + - "Filterable" + description: "__Filterable__ The city for this child account's billing address." + type: "string" + state: + maxLength: 24 + example: "CA" + x-linode-filterable: true + x-akamai: + labels: + - "Filterable" + description: "__Filterable__ The state or province for the billing address (`address_1` and `address_2, if applicable`). If in the United States (US) or Canada (CA), this is the two-letter ISO 3166 State or Province code.\n\n__Note__. If this is a US military address, use state abbreviations (AA, AE, AP)." + type: "string" + credit_card: + readOnly: true + additionalProperties: false + description: "__Read-only__ Information for the credit card you've assigned to this child account." + type: "object" + properties: + expiry: + type: "string" + description: "The expiration month and year of the credit card." + example: "11/2024" + last_four: + description: "The last four digits of the credit card." + type: "string" + example: 1111 + euuid: + readOnly: true + example: "A1BC2DEF-34GH-567I-J890KLMN12O34P56" + format: "uuid" + type: "string" + description: "__Read-only__ An external, unique identifier that Akamai assigned to the child account." + address_1: + description: "__Filterable__ First line of this child account's billing address." + type: "string" + x-akamai: + labels: + - "Filterable" + example: "123 Main Street" + maxLength: 64 + x-linode-filterable: true + country: + x-linode-filterable: true + example: "US" + x-akamai: + labels: + - "Filterable" + description: "__Filterable__ The two-letter ISO 3166 country code for this child account's billing address." + type: "string" + last_name: + maxLength: 50 + example: "Smith" + x-linode-filterable: true + type: "string" + description: "__Filterable__ The last name of the owner of this child account. It can't include any of these characters: `<` `>` `(` `)` `\"` `=`." + x-linode-cli-display: 2 + x-akamai: + labels: + - "Filterable" + balance_uninvoiced: + x-linode-cli-display: 4 + type: "number" + description: "__Read-only__ This child account's current estimated invoice in US dollars. This is not your final invoice balance. Transfer charges are not included in the estimate." + readOnly: true + example: 145 + email: + x-akamai: + labels: + - "Filterable" + x-linode-cli-display: 3 + type: "string" + description: "__Filterable__ The email address of the owner of this child account." + x-linode-filterable: true + example: "john.smith@linode.com" + maxLength: 128 + billing_source: + description: "__Read-only__ The source of service charges for this account, as determined by its relationship with Akamai. The API returns a value of `external` to describe a child account in a parent-child account environment." + type: "string" + enum: + - "external" + example: "external" + readOnly: true + company: + x-linode-filterable: true + maxLength: 128 + example: "Acme" + x-akamai: + labels: + - "Filterable" + type: "string" + description: "__Filterable__ The company name for the owner of this child account. It can't include any of these characters: `<` `>` `(` `)` `\"` `=`. You can't change this value yourself. We use it to create the proxy users that a parent account uses to access a child account. Talk to your account team if you need to change this value." + phone: + type: "string" + description: "__Filterable__ The phone number for the owner of this child account." + x-akamai: + labels: + - "Filterable" + maxLength: 32 + example: "858-555-1212" + x-linode-filterable: true + tax_id: + maxLength: 25 + example: "ATU99999999" + description: "The tax identification number for this child account. Use this for tax calculations in some countries. If you live in a country that doesn't collect taxes, ensure this is an empty string (`\"\"`)." + type: "string" + type: "object" + description: "Child account object." + added-post-client: + allOf: + - + properties: + redirect_uri: + type: "string" + description: "The location a successful log in from [login.linode.com](https://login.linode.com) 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." + format: "url" + x-linode-cli-display: 5 + example: "https://example.org/oauth/callback" + secret: + type: "string" + description: "__Read-only__ The OAuth Client secret, used in the OAuth exchange. This is returned as `` except when an OAuth Client is created or its secret is reset. This is a secret, and should not be shared or disclosed publicly." + readOnly: true + example: "" + id: + readOnly: true + example: "2737bf16b39ab5d7b4a1" + x-linode-cli-display: 1 + description: "__Read-only__ The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret)." + type: "string" + status: + x-linode-cli-color: + suspended: "red" + default_: "white" + enum: + - "active" + - "disabled" + - "suspended" + example: "active" + readOnly: true + description: "__Read-only__ The status of this application. `active` by default." + type: "string" + x-linode-cli-display: 3 + thumbnail_url: + nullable: true + type: "string" + description: "__Read-only__ The URL where this client's thumbnail may be viewed, or `null` if this client does not have a thumbnail set." + format: "url" + example: "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail" + readOnly: true + public: + example: false + x-linode-filterable: true + type: "boolean" + description: "__Filterable__ If this is a public or private OAuth Client. Public clients have a slightly different authentication workflow than private clients. See the [OAuth spec](https://oauth.net/2/) for more details." + x-linode-cli-display: 4 + default: false + x-akamai: + labels: + - "Filterable" + label: + minLength: 1 + x-akamai: + labels: + - "Filterable" + x-linode-cli-display: 2 + description: "__Filterable__ The name of this application. This will be presented to users when they are asked to grant it access to their Account." + type: "string" + x-linode-filterable: true + example: "Test_Client_1" + maxLength: 512 + x-akamai: + file-path: "schemas/oauth-client.yaml" + description: "A third-party application registered to Linode that users may log into with their Linode account through our authentication server at [login.linode.com](https://login.linode.com). 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." + type: "object" + additionalProperties: false + required: + - "label" + - "redirect_uri" + x-akamai: + file-path: "schemas/added-post-client.yaml" + payment-method: + additionalProperties: false + properties: + data: + oneOf: + - + x-linode-ref-name: "Credit Card" + title: "Credit card" + properties: + card_type: + description: "__Read-only__ The type of credit card." + type: "string" + example: "Discover" + readOnly: true + last_four: + type: "string" + description: "__Read-only__ The last four digits of the credit card number." + readOnly: true + example: "1234" + expiry: + example: "06/2022" + readOnly: true + type: "string" + description: "__Read-only__ The expiration month and year of the credit card." + format: "MM/YYYY" + x-akamai: + file-path: "schemas/credit-card-data.yaml" + type: "object" + description: "Credit card information." + additionalProperties: false + - + type: "object" + description: "Google Pay information." + properties: + last_four: + example: "1234" + readOnly: true + description: "__Read-only__ The last four digits of the credit card number." + type: "string" + expiry: + readOnly: true + example: "06/2022" + format: "MM/YYYY" + type: "string" + description: "__Read-only__ The expiration month and year of the credit card." + card_type: + readOnly: true + example: "Discover" + type: "string" + description: "__Read-only__ The type of credit card." + x-akamai: + file-path: "schemas/google-pay-data.yaml" + x-linode-ref-name: "Google Pay" + title: "Google Pay" + additionalProperties: false + - + title: "Paypal" + x-linode-ref-name: "Paypal" + additionalProperties: false + type: "object" + description: "PayPal information." + x-akamai: + file-path: "schemas/paypal-data.yaml" + properties: + paypal_id: + readOnly: true + example: "ABC1234567890" + type: "string" + description: "__Read-only__ PayPal Merchant ID associated with your PayPal account." + email: + type: "string" + description: "__Read-only__ The email address associated with your PayPal account." + readOnly: true + example: "example@linode.com" + x-linode-cli-format: "json" + x-linode-cli-display: 4 + created: + example: "2018-01-15T00:01:01" + readOnly: true + description: "__Read-only__ When the Payment Method was added to the Account." + type: "string" + format: "date-time" + is_default: + type: "boolean" + description: "Whether this Payment Method is the default method for automatically processing service charges." + x-linode-cli-display: 3 + example: true + id: + x-linode-cli-display: 1 + description: "The unique ID of this Payment Method." + type: "integer" + example: 123 + type: + example: "credit_card" + enum: + - "credit_card" + - "google_pay" + - "paypal" + x-linode-cli-display: 2 + type: "string" + description: "The type of Payment Method." + x-akamai: + file-path: "schemas/payment-method.yaml" + type: "object" + description: "Payment Method Response Object." + paypal-execute: + additionalProperties: false + properties: + payer_id: + description: "The PayerID returned by PayPal during the transaction authorization process." + type: "string" + example: "ABCDEFGHIJKLM" + payment_id: + example: "PAY-1234567890ABCDEFGHIJKLMN" + description: "The PaymentID returned from [Stage a PayPal payment](https://techdocs.akamai.com/linode-api/reference/post-pay-pal-payment) that has been approved with PayPal." + type: "string" + x-akamai: + file-path: "schemas/paypal-execute.yaml" + type: "object" + description: "An object representing an execution of Payment to PayPal to capture the funds and credit your Linode Account." + required: + - "payer_id" + - "payment_id" + added-post-beta-program: + additionalProperties: false + properties: + id: + x-linode-cli-display: 1 + description: "The unique identifier of the Beta Program." + type: "string" + example: "example_open" + x-akamai: + file-path: "schemas/added-post-beta-program.yaml" + description: "The Beta Program ID to enroll in for your Account." + type: "object" + required: + - "id" + oauth-client: + additionalProperties: false + properties: + secret: + readOnly: true + example: "" + type: "string" + description: "__Read-only__ The OAuth Client secret, used in the OAuth exchange. This is returned as `` except when an OAuth Client is created or its secret is reset. This is a secret, and should not be shared or disclosed publicly." + id: + x-linode-cli-display: 1 + description: "__Read-only__ The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret)." + type: "string" + readOnly: true + example: "2737bf16b39ab5d7b4a1" + redirect_uri: + example: "https://example.org/oauth/callback" + x-linode-cli-display: 5 + format: "url" + type: "string" + description: "The location a successful log in from [login.linode.com](https://login.linode.com) 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." + public: + x-linode-cli-display: 4 + x-akamai: + labels: + - "Filterable" default: false - responses: - '200': - description: A paginated list of IP Addresses. - content: - application/json: - schema: - $ref: '#/components/schemas/IPAddressesListResponse' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/networking/ips?skip_ipv6_rdns=true - - 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/203.0.113.1 - - lang: CLI - source: > - linode-cli networking ip-update \ - 203.0.113.1 \ - --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. - * Shared IP addresses cannot be swapped between Linodes. - - [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)) - - **Note:** Addresses with an active 1:1 NAT to a VPC Interface address cannot be assigned to other Linodes. - 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 - 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. - - **Note:** A public IPv4 address cannot be shared if it is configured for a 1:1 NAT on a `vpc` purpose Configuration Profile Interface. - 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/v4beta/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 - - ls - 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 be assigned to Linode compute instances and NodeBalancers. - - * A Firewall can be assigned to multiple services at a time. - - * A Firewall can be assigned during Linode creation by utilizing the `firewall_id` [Linode Create Request](/docs/api/linode-instances/#linode-create__request-body-schema) property. - - * A service 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. - - * Firewalls apply to all of a Linode's non-`vlan` purpose Configuration Profile Interfaces. - - * Assigned Linodes must not have any ongoing live migrations. - - * 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 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 be created for Linode compute instances and NodeBalancers. - - Additional devices can be assigned after Firewall creation by using the [Firewall Device Create](#firewall-device-create) command. - properties: - linodes: - description: > - An array of Linode IDs. A Firewall Device is created for each ID. - type: array - items: - type: integer - example: - - 123 - - 456 - nodebalancers: - description: | - An array containing a NodeBalancer ID. A Firewall Device is created for the ID. - - * Only one NodeBalancer can be assigned to a Firewall at a time. - * Firewalls only apply to inbound TCP traffic to NodeBalancers. - type: array - items: - type: integer - example: - - 321 - 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", - "198.51.100.2/32" - ], - "ipv6": [ - "2001:DB8::/128" - ] - }, - "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", - "198.51.100.2/32" - ], - "ipv6": [ - "2001:DB8::/128" - ] - }, - "action": "ACCEPT", - "label": "outbound-rule123", - "description": "An example outbound rule description." - } - ] - }, - "devices": { - "linodes": [ - 123, - 456 - ], - "nodebalancers": [ - 321 - ] - }, - "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.0/24", "198.51.100.2/32"], "ipv6": ["2001:DB8::/128"]}, "action": "ACCEPT"}]' \ - --rules.outbound '[{"protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.0/24", "198.51.100.2/32"],"ipv6": ["2001:DB8::/128"]}, "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. - - * Assigned Linodes must not have any ongoing live migrations. - - * If a Firewall's status is changed with this endpoint, a corresponding `firewall_enable` or - `firewall_disable` Event will be generated. - - 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 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. - 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 - - rm - security: - - personalAccessToken: [] - - oauth: - - firewall:read_write - description: | - Delete a Firewall resource by its ID. This removes all of the Firewall's Rules - from any services that the Firewall was assigned to. - - * Assigned Linodes must not have any ongoing live migrations. - - * 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 service (referred to as the Device's `entity`). - 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' - example: - - { - "created": "2018-01-01T00:01:01", - "entity": { - "id": 123, - "label": "my-linode", - "type": "linode", - "url": "/v4/linode/instances/123" - }, - "id": 456, - "updated": "2018-01-02T00:01:01" - } - - { - "created": "2018-01-01T00:01:01", - "entity": { - "id": 321, - "label": "my-nodebalancer", - "type": "nodebalancer", - "url": "/v4/nodebalancers/123" - }, - "id": 654, - "updated": "2018-01-02T00:01:01" - } - 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, Devices with `linode` and `nodebalancer` entity types are accepted. - - * Firewalls only apply to inbound TCP traffic to NodeBalancers. - - * A Firewall can be assigned to multiple services at a time. - - * A service 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. - - * Assigned Linodes must not have any ongoing live migrations. - - * 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 service (referred to as the Device's `entity`). - 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 service it was - assigned to by the Device. This removes all of the Firewall's Rules from the - service. If any other Firewalls have been assigned to the service, then those Rules - remain in effect. - - * Assigned Linodes must not have any ongoing live migrations. - - * 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: - x-linode-cli-subtables: - - inbound - - outbound - 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. - - * Assigned Linodes must not have any ongoing live migrations. - - * **Note:** This command replaces all of a Firewall's `inbound` and `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: - x-linode-cli-subtables: - - inbound - - outbound - 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", - "198.51.100.2/32" - ], - "ipv6": [ - "2001:DB8::/128" - ] - }, - "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", - "198.51.100.2/32" - ], - "ipv6": [ - "2001:DB8::/128" - ] - }, - "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.0/24", "198.51.100.2/32"], "ipv6": ["2001:DB8::/128"]}}]' \ - --outbound '[{"action":"DROP","protocol": "TCP", "ports": "49152-65535", "addresses": {"ipv4": ["192.0.2.0/24", "198.51.100.2/32"], "ipv6": ["2001:DB8::/128`"]}}]' - /networking/vlans: - x-linode-cli-command: vlans - get: - x-linode-grant: read_only - servers: - - url: https://api.linode.com/v4 - 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 the [VLANs Overview](/docs/products/networking/vlans/#technical-specifications) to view additional specifications and limitations. - operationId: getVLANs - x-linode-cli-action: - - list - - ls - 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/v4/networking/vlans/ - - lang: CLI - source: > - linode-cli 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 - - ls - 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. Only available in [Regions](/docs/api/regions/#regions-list) with "NodeBalancers" in their `capabilities`. - - 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' - firewall_id: - type: integer - description: | - The ID of the Firewall to assign to the NodeBalancer. - - * Only one NodeBalancer can be assigned to a Firewall at a time. - * Firewalls only apply to inbound TCP traffic to NodeBalancers. - tags: - description: | - An array of Tags applied to this object. Tags are for organizational purposes only. - type: array - items: - type: string - example: - - test - - web-dev-team - 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 - - rm - 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-update \ - 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}/firewalls: - x-linode-cli-command: nodebalancers - parameters: - - name: nodeBalancerId - in: path - description: The ID of the NodeBalancer to access. - required: true - schema: - type: integer - get: - operationId: getNodeBalancerFirewalls - x-linode-grant: read_only - tags: - - NodeBalancers - summary: Firewalls List - description: > - View information for Firewalls assigned to this NodeBalancer. - x-linode-cli-action: firewalls - security: - - personalAccessToken: [] - - oauth: - - nodebalancers:read_only - responses: - '200': - description: Returns a paginated list of Firewalls assigned to this NodeBalancer. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Firewall' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/nodebalancers/$nodeBalancerId/firewalls \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli nodebalancers firewalls $nodeBalancerId - /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 specified cluster. - - Accounts with negative balances cannot access this command. - - If the bucket already exists and is owned by you, this endpoint returns 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: "..." - 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: "..." - 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 - items: - $ref: '#/components/schemas/ObjectStorageObject' - 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 - 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. - - * Accounts with negative balances cannot access this command. - * A successful request triggers an `obj_access_key_create` event. - * 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. - - * A successful request triggers an `obj_access_key_update` event. - 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. - - * A successful request triggers an `obj_access_key_delete` event. - 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 Overview](/docs/products/storage/object-storage/#pricing) - 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. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * You can't edit the `email` for a child account parent user (proxy user). This value is fixed and set when you provision this environment. - 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. - - **Parent and child accounts** - - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: - - * If you're using a child account parent user (proxy user), you can't create this form of token. The only token available to a proxy user is one that lets you run operations in a child account. These are created via the [Proxy User Token Create](#proxy-user-token-create) operation. - 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 access [scopes](/docs/api#oauth-reference) to grant to the created token. These cannot be changed after creation, and may not exceed the scopes of the acting token. - - If omitted or entered with a wildcard character (`*`), the new token will have the same scopes as the acting token. - - Multiple scopes are separated by a space character (` `). - - For example, `linodes:read_write account:read_only`. - 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 - - ls - 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 - - ls - 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/SSHKey' - 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`. - - Only SSH key labels can be updated. - 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: - type: object - properties: - label: - $ref: '#/components/schemas/SSHKey/properties/label' - 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/sshkeys/42 - - lang: CLI - source: > - linode-cli sshkeys 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 - - rm - 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 "Authoriztion: Bearer $TOKEN" \ - -X DELETE \ - https://api.linode.com/v4/profile/sshkeys/42 - - lang: CLI - source: > - linode-cli sshkeys 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-action: 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 "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-action: 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-action: 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 "Authorization: Bearer $TOKEN" \ - 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. Overwrites any existing preferences for this user. - - Total length cannot exceed 65,535 characters. - maxLength: 65535 - 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", - "key2": "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 - - ls - 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 - /regions/{regionId}/availability: - 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 Availability View - description: > - Returns availability data for a single Region. - operationId: getRegionAvailability - x-linode-cli-action: view-avail - responses: - '200': - description: The availability data for a single Region. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/RegionAvailability' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/regions/us-east/availability - - lang: CLI - source: > - linode-cli regions view-avail us-east - /regions/availability: - x-linode-cli-command: regions - get: - tags: - - Regions - summary: Regions Availability List - description: | - Returns availability data for all Regions. - - Currently, this command returns availability of select premium and GPU plans for select regions. - operationId: getRegionsAvailability - x-linode-cli-action: list-avail - responses: - '200': - description: Returns a Region Availability object. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - properties: - data: - type: array - items: - $ref: '#/components/schemas/RegionAvailability' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/regions/availability - - lang: CLI - source: > - linode-cli regions list-avail - /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 - - ls - 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: Support 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. - - The file attachment is submitted in the request as multipart/form-data. - - **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: unrestricted 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. - - **Important**: You must be an unrestricted User in order to access, add, or modify - Tags information. - operationId: getTags - x-linode-cli-action: - - list - - ls - 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: - x-linode-grant: unrestricted only - 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 access, add, or modify - Tags information. - 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/{tagLabel}: - x-linode-cli-command: tags - parameters: - - name: tagLabel - in: path - schema: - type: string - description: The `label` of the Tag to access. - 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. - - **Important**: You must be an unrestricted User in order to access, add, or modify - Tags information. - 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/$tagLabel - delete: - summary: Tag Delete - description: > - Remove a Tag from all objects and delete it. - - - **Important**: You must be an unrestricted User in order to access, add, or modify - Tags information. - tags: - - Tags - operationId: deleteTag - x-linode-cli-action: - - delete - - rm - 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 - - ls - 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 - - rm - 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_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. - - Volumes are automatically detached from deleted Linodes. - 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: - $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 '{ - "size": 30 - }' \ - https://api.linode.com/v4/volumes/12345/resize - - lang: CLI - source: > - linode-cli volumes resize 12345 \ - --size 30 - /vpcs: - x-linode-cli-command: vpcs - get: - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - tags: - - VPCs - summary: VPCs List - servers: - - url: https://api.linode.com/v4 - description: | - Display all VPCs on your account. - operationId: getVPCs - x-linode-cli-action: - - list - - ls - security: - - personalAccessToken: [] - - oauth: [] - responses: - '200': - description: A paginated list of VPC objects. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - properties: - data: - type: array - items: - $ref: '#/components/schemas/VPC' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli vpcs list - post: - x-linode-grant: add_vpcs - tags: - - VPCs - summary: VPC Create - servers: - - url: https://api.linode.com/v4 - description: | - Create a new VPC and optionally associated VPC Subnets. - * Users must have the `add_vpc` grant to access this command. - * A successful request triggers a `vpc_create` event and `subnet_create` events for any created VPC Subnets. - - Once a VPC is created, it can be attached to a Linode by assigning a VPC Subnet to one of the Linode's Configuration Profile Interfaces. This step can be accomplished with the following commands: - * 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)) - * Configuration Profile Interface Add ([POST /linode/instances/{linodeId}/configs/{configId}/interfaces](/docs/api/linode-instances/#configuration-profile-interface-add)) - operationId: createVPC - x-linode-cli-action: create - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - requestBody: - description: | - VPC Create request object. - required: true - content: - application/json: - schema: - allOf: - - required: - - label - - region - - properties: - subnets: - required: - - ipv4 - - label - - $ref: '#/components/schemas/VPC' - responses: - '200': - description: The new VPC. - content: - application/json: - schema: - $ref: '#/components/schemas/VPC' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "description": "A description of my VPC.", - "label": "cool-vpc", - "region": "us-east", - "subnets": [ - { - "label": "cool-vpc-subnet", - "ipv4": "10.0.1.0/24" - } - ] - }' - - lang: CLI - source: > - linode-cli vpcs create \ - --description "A description of my VPC." \ - --label cool-vpc \ - --region us-east \ - --subnets.label cool-vpc-subnet \ - --subnets.ipv4 10.0.1.0/24 - /vpcs/{vpcId}: - x-linode-cli-command: vpcs - parameters: - - $ref: '#/components/parameters/vpcId' - delete: - x-linode-grant: read_write - summary: VPC Delete - servers: - - url: https://api.linode.com/v4 - description: | - Delete a single VPC and all of its Subnets. - * The User accessing this command must have `read_write` grants to the VPC. - * A successful request triggers a `vpc_delete` event and `subnet_delete` events for each deleted VPC Subnet. - * All of the VPC's Subnets must be eligible for deletion. Accordingly, all Configuration Profile Interfaces that each Subnet is assigned to must first be deleted. If those Interfaces are active, the associated Linodes must first be shut down before they can be removed. If any Subnet cannot be deleted, then neither the VPC nor any of its Subnets are deleted. - tags: - - VPCs - operationId: deleteVPC - x-linode-cli-action: delete - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - responses: - '200': - description: Delete request successful. - content: - application/json: - schema: - type: object - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId \ - -H "Authorization: Bearer $TOKEN" \ - -X DELETE - - lang: CLI - source: > - linode-cli vpcs delete $vpcId - get: - summary: VPC View - servers: - - url: https://api.linode.com/v4 - description: | - Get information about a single VPC. - tags: - - VPCs - operationId: getVPC - x-linode-cli-action: view - security: - - personalAccessToken: [] - - oauth: [] - responses: - '200': - description: A VPC object. - content: - application/json: - schema: - $ref: '#/components/schemas/VPC' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli vpcs view $vpcId - put: - x-linode-grant: read_write - tags: - - VPCs - summary: VPC Update - servers: - - url: https://api.linode.com/v4 - description: | - Update an existing VPC. - * The User accessing this command must have `read_write` grants to the VPC. - * A successful request triggers a `vpc_update` event. - - To update a VPC's Subnet, use the [VPC Subnet Update](#vpc-subnet-update) command. - operationId: updateVPC - x-linode-cli-action: update - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - requestBody: - description: | - VPC Update request object. - required: true - content: - application/json: - schema: - type: object - description: A VPC Update request object. - properties: - description: - $ref: '#/components/schemas/VPC/properties/description' - label: - $ref: '#/components/schemas/VPC/properties/label' - responses: - '200': - description: The updated VPC. - content: - application/json: - schema: - $ref: '#/components/schemas/VPC' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X PUT -d '{ - "description": "A description of my VPC.", - "label": "cool-vpc" - }' - - lang: CLI - source: > - linode-cli vpcs update $vpcId \ - --description "A description of my VPC." - --label cool-vpc - /vpcs/ips: - get: - x-linode-grant: read_only - tags: - - VPCs - summary: VPC IP Addresses List - servers: - - url: https://api.linode.com/v4 - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - Returns a paginated list of all VPC IP addresses and address ranges on your account. - - **Note**: If a Linode has several configuration profiles that include a VPC interface, address information for all of them is listed in the response. Since VPCs can use the same address space, you may see duplicate IP addresses. - operationId: getAllVPCIPs - x-linode-cli-action: - - ip-list - - ip-ls - security: - - personalAccessToken: [] - - oauth: - - ips:read_only - responses: - '200': - description: A paginated list of VPC interface IP addresses. - content: - application/json: - schema: - properties: - data: - type: array - items: - $ref: '#/components/schemas/IPAddressesVPC' - 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/vpcs/ips - - lang: CLI - source: > - linode-cli vpcs ip list - /vpcs/{vpcId}/ips: - parameters: - - $ref: '#/components/parameters/vpcId' - get: - tags: - - VPCs - summary: VPC IP Addresses View - servers: - - url: https://api.linode.com/v4 - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - Returns a paginated list of IP addresses for a single VPC. - operationId: getVPCIPs - x-linode-cli-action: - - ip-list - - ip-ls - security: - - personalAccessToken: [] - - oauth: - - ips:read_only - responses: - '200': - description: The IP addresses for the requested VPC. - content: - application/json: - schema: - $ref: '#/components/schemas/IPAddressesVPC' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/vpcs/123/ips - - lang: CLI - source: > - linode-cli vpcs ip-list 123 - /vpcs/{vpcId}/subnets: - x-linode-cli-command: vpcs - parameters: - - $ref: '#/components/parameters/vpcId' - get: - tags: - - VPCs - summary: VPC Subnets List - servers: - - url: https://api.linode.com/v4 - parameters: - - $ref: '#/components/parameters/pageOffset' - - $ref: '#/components/parameters/pageSize' - description: | - Get information about all VPC Subnets associated with a VPC. - operationId: getVPCSubnets - x-linode-cli-action: - - subnets-list - - subnets-ls - security: - - personalAccessToken: [] - - oauth: [] - responses: - '200': - description: A paginated list of VPC Subnet objects. - content: - application/json: - schema: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - properties: - data: - type: array - items: - $ref: '#/components/schemas/VPCSubnet' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId/subnets \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli vpcs subnets-list $vpcId - post: - x-linode-grant: read_write - tags: - - VPCs - summary: VPC Subnet Create - servers: - - url: https://api.linode.com/v4 - description: | - Create a VPC Subnet. - * The User accessing this command must have `read_write` grants to the VPC. - * A successful request triggers a `subnet_create` event. - - Once a VPC Subnet is created, it can be attached to a Linode by assigning the Subnet to one of the Linode's Configuration Profile Interfaces. This step can be accomplished with the following commands: - * 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)) - * Configuration Profile Interface Add ([POST /linode/instances/{linodeId}/configs/{configId}/interfaces](/docs/api/linode-instances/#configuration-profile-interface-add)) - operationId: createVPCSubnet - x-linode-cli-action: subnet-create - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - requestBody: - description: | - VPC Subnet Create request object. - required: true - content: - application/json: - schema: - type: object - description: VPC Subnet Create request object - required: - - ipv4 - - label - properties: - label: - $ref: '#/components/schemas/VPCSubnet/properties/label' - ipv4: - $ref: '#/components/schemas/VPCSubnet/properties/ipv4' - # ipv6: - # $ref: '#/components/schemas/VPCSubnet/properties/ipv6' - responses: - '200': - description: The new VPC Subnet. - content: - application/json: - schema: - $ref: '#/components/schemas/VPCSubnet' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId/subnets \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X POST -d '{ - "label": "cool-vpc-subnet", - "ipv4": "10.0.1.0/24", - }' - - lang: CLI - source: > - linode-cli vpcs subnet-create $vpcId \ - --label cool-vpc-subnet \ - --ipv4 10.0.1.0/24 - /vpcs/{vpcId}/subnets/{vpcSubnetId}: - x-linode-cli-command: vpcs - parameters: - - $ref: '#/components/parameters/vpcId' - - $ref: '#/components/parameters/vpcSubnetId' - delete: - x-linode-grant: read_write - summary: VPC Subnet Delete - servers: - - url: https://api.linode.com/v4 - description: | - Delete a single VPC Subnet. - - The user accessing this command must have `read_write` grants to the VPC. A successful request triggers a `subnet_delete` event. - - **Note:** You need to delete all the Configuration Profile Interfaces that this Subnet is assigned to before you can delete it. If those Interfaces are active, the associated Linode needs to be shut down before they can be removed. - tags: - - VPCs - operationId: deleteVPCSubnet - x-linode-cli-action: subnet-delete - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - responses: - '200': - description: Delete request successful. - content: - application/json: - schema: - type: object - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId/subnets/$vpcSubnetId \ - -H "Authorization: Bearer $TOKEN" \ - -X DELETE - - lang: CLI - source: > - linode-cli vpcs subnet-delete $vpcId $vpcSubnetId - get: - summary: VPC Subnet View - servers: - - url: https://api.linode.com/v4 - description: | - Get information about a single VPC Subnet. - tags: - - VPCs - operationId: getVPCSubnet - x-linode-cli-action: subnet-view - security: - - personalAccessToken: [] - - oauth: [] - responses: - '200': - description: A VPC Subnet object. - content: - application/json: - schema: - $ref: '#/components/schemas/VPCSubnet' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId/subnets/$vpcSubnetId \ - -H "Authorization: Bearer $TOKEN" - - lang: CLI - source: > - linode-cli vpcs subnet-view $vpcId #vpcSubnetId - put: - x-linode-grant: read_write - tags: - - VPCs - summary: VPC Subnet Update - servers: - - url: https://api.linode.com/v4 - description: | - Update a VPC Subnet. - * The User accessing this command must have `read_write` grants to the VPC. - * A successful request triggers a `subnet_update` event. - operationId: updateVPCSubnet - x-linode-cli-action: subnet-update - security: - - personalAccessToken: [] - - oauth: - - vpc:read_write - requestBody: - description: | - VPC Update request object. - required: true - content: - application/json: - schema: - type: object - description: A VPC Subnet Update request object. - properties: - label: - $ref: '#/components/schemas/VPCSubnet/properties/label' - responses: - '200': - description: The updated VPC Subnet. - content: - application/json: - schema: - $ref: '#/components/schemas/VPCSubnet' - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl https://api.linode.com/v4/vpcs/$vpcId/subnets/$vpcSubnetId \ - -H "Authorization: Bearer $TOKEN" \ - -H "Content-Type: application/json" \ - -X PUT -d '{ - "label": "cool-vpc-subnet" - }' - - lang: CLI - source: > - linode-cli vpcs subnet-update $vpcId \ - --label cool-vpc-subnet -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. - '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. - 'vpc:read_write': Allows access to all endpoints related to VPC and Subnet creation, updating, and deletion. - 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: - betaId: - name: betaId - in: path - description: The ID of the Beta Program. - required: true - schema: - type: string - configId: - name: configId - in: path - description: The `id` of the Configuration Profile. - required: true - schema: - type: integer - linodeId: - name: linodeId - in: path - description: The `id` of the Linode. - required: true - schema: - type: integer - 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: 500 - default: 100 - vpcId: - name: vpcId - in: path - schema: - type: integer - required: true - description: The `id` of the VPC. - vpcSubnetId: - name: vpcSubnetId - in: path - schema: - type: integer - required: true - description: The `id` of the VPC Subnet. - 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 date and time 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 + description: "__Filterable__ If this is a public or private OAuth Client. Public clients have a slightly different authentication workflow than private clients. See the [OAuth spec](https://oauth.net/2/) for more details." + type: "boolean" + example: false + x-linode-filterable: true + label: + minLength: 1 + type: "string" + description: "__Filterable__ The name of this application. This will be presented to users when they are asked to grant it access to their Account." + x-akamai: + labels: + - "Filterable" + x-linode-cli-display: 2 + x-linode-filterable: true + example: "Test_Client_1" + maxLength: 512 + thumbnail_url: readOnly: true - city: - type: string - description: The city for this Account's billing address. - maxLength: 24 - example: Philadelphia - credit_card: - type: object + example: "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail" + format: "url" + nullable: true + description: "__Read-only__ The URL where this client's thumbnail may be viewed, or `null` if this client does not have a thumbnail set." + type: "string" + status: + x-linode-cli-color: + suspended: "red" + default_: "white" 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. - - Must not include any of the following characters: `<` `>` `(` `)` `"` `=` - 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 + enum: + - "active" + - "disabled" + - "suspended" + example: "active" x-linode-cli-display: 3 - first_name: - type: string - description: | - The first name of the person associated with this Account. - - Must not include any of the following characters: `<` `>` `(` `)` `"` `=` - maxLength: 50 - example: John - x-linode-cli-display: 1 - last_name: - type: string - description: | - The last name of the person associated with this Account. - - Must not include any of the following characters: `<` `>` `(` `)` `"` `=` - maxLength: 50 - example: Smith - x-linode-cli-display: 2 - phone: - type: string - description: The phone number associated with this Account. + description: "__Read-only__ The status of this application. `active` by default." + type: "string" + x-akamai: + file-path: "schemas/oauth-client.yaml" + description: "A third-party application registered to Linode that users may log into with their Linode account through our authentication server at [login.linode.com](https://login.linode.com). 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." + type: "object" + added-post-promo-credit: + type: "object" + properties: + promo_code: 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 + minLength: 1 + description: "The Promo Code." + type: "string" + x-akamai: + file-path: "schemas/added-post-promo-credit.yaml" + required: + - "promo_code" + additionalProperties: false + proxy-user-token: + description: "The token generated manually for a child account so its proxy user can access the API and CLI without going through an OAuth login." + type: "object" + x-akamai: + file-path: "schemas/proxy-user-token.yaml" + properties: + label: + example: "parent1_1234_2024-05-01T00:01:01" + maxLength: 100 + x-linode-filterable: true + minLength: 1 + x-linode-cli-display: 2 + x-akamai: + labels: + - "Filterable" + description: "__Filterable__ The name of the token. The API automatically sets this to `__