From f0254fe565ed0c2148487f98144b19518f3c6596 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Mon, 17 Jun 2024 12:17:40 -0400 Subject: [PATCH] Import Linode API spec generated by Akamai tooling --- .../linode/linode-api-docs/v4/openapi.yaml | 124004 ++++++++++++--- go.mod | 2 + 2 files changed, 98180 insertions(+), 25826 deletions(-) diff --git a/_vendor/github.com/linode/linode-api-docs/v4/openapi.yaml b/_vendor/github.com/linode/linode-api-docs/v4/openapi.yaml index 1c6e43bdfc..d097acd3e9 100644 --- a/_vendor/github.com/linode/linode-api-docs/v4/openapi.yaml +++ b/_vendor/github.com/linode/linode-api-docs/v4/openapi.yaml @@ -1,29371 +1,101723 @@ openapi: 3.0.1 info: + description: | + Add a Cloud Computing instance so you can build, release, and scale applications faster with virtual machines. + title: 'Akamai: Linode API' version: 4.176.0 - title: Linode API + contact: + name: Linode + email: support@linode.com + url: https://linode.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html +servers: +- url: https://api.linode.com/v4 +- url: https://api.linode.com/v4beta +tags: +- name: Account 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). + Use the Account endpoints to manage user settings, billing, and payments. You can also initiate and maintain OAuth client + application authentication, enable the Linode Managed service, and create new + users on your account. +- name: Beta programs + description: | + Use the Beta Programs endpoint to view information about available beta programs. To sign up for eligible beta programs, + run the _Enroll in a Beta program_ operation. +- name: Databases + description: | + Managed Databases is Linode's fully-managed, high-performance database service. Use the Managed Databases endpoints to create + and manage database clusters. +- name: Domains + description: | + Use the Domains endpoints to create and manage domains and domain records on your account. +- name: Images + description: | + Use the Images endpoints to capture, store, and manage custom Linode images. +- name: Linode instances + description: | + Use the Linode Instances endpoints to create, configure, and manage your Linode instances. You can also manage the Linode + Backup service; maintain and manage configuration profiles; create and maintain + disks, initiate a host migration; view Linode Instance statistics; and more. +- name: Linode types + description: | + Use the Linode Types endpoints to retrieve information about Linode plan types, including pricing information, hardware resources, + and network transfer allotment. +- name: Linode Kubernetes Engine (LKE) + description: | + Linode Kubernetes Engine (LKE) is Linode's managed Kubernetes service. Use the LKE endpoints to create and manage Kubernetes + clusters and their associated Node Pools. +- name: Longview + description: | + Longview is Linode's system-level monitoring and graphing service. Use the Longview endpoints to manage your Longview subscription + and plan and to create and maintain Longview clients. +- name: Managed + description: | + Managed is Linode's incident response service. Use the Managed endpoints to register a service to be monitored by the + Managed Service team, provide secure access to your managed services, view information + about detected issues, and more. +- name: Networking + description: | + Use the Networking endpoints to view all IP addresses on your account, reorganize assigned IPv4 addresses, update RDNS, + and configure IP sharing. +- name: NodeBalancers + description: | + NodeBalancers is Linode's load balancing service. Use the NodeBalancers endpoints to create and manage NodeBalancers. You + can also create and maintain configurations; create and maintain nodes, and view + statistics. +- name: Object storage + description: | + Object Storage is Linode's S3-compatible data storage service. Use the Object Storage endpoints to create and maintaining + buckets, add and remove objects from buckets, create and maintain Object Storage + keys, and cancel the Object Storage service. +- name: Profile + description: | + Use the Profile endpoints to manage your Linode user profile preferences and security settings. This includes creating + and maintaining personal access tokens, creating and maintaining SSH keys, confirming + and enabling two-factor authentication, and updating user and profile preferences. +- name: Regions + description: | + Use the Regions endpoints to view information about the various Linode data center regions, including the service capabilities + for each region, country, status, and more. +- name: StackScripts + description: | + Linode StackScripts allow you to create reusable scripts to configure new Linode instances. Use the StackScripts endpoints + to create and manage StackScripts on your account. +- name: Support + description: | + Use the Support endpoints to open, view, and close Linode Support tickets. You can also create and manage your Support + ticket replies. +- name: Tags + description: | + Tags allow you to organize and group your various Linode services. Use the Tags endpoints to create, assign, and delete + your account tags. +- name: Volumes + description: | + Volumes is Linode's block storage service. Use the Volumes endpoints to create, attach, and manage your account Volumes. +- name: VPCs + description: | + Use the VPCs endpoints to view, create, and manage Virtual Private Cloud (VPC) and VPC Subnet resources. +x-readme: + samples-languages: + - curl + - python + - node +paths: + /nodebalancers/{nodeBalancerId}/configs/{configId}: + x-akamai: + file-path: paths/node-balancer-config.yaml + path-info: /nodebalancers/{nodeBalancerId}/configs/{configId} + parameters: + - name: nodeBalancerId + in: path + description: | + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml + required: true + schema: + type: integer + - name: configId + in: path + description: | + The ID of the Config to access + example: '{{configId}}' + x-akamai: + file-path: parameters/config-id.yaml + required: true + schema: + type: integer + get: + operationId: get-node-balancer-config + summary: Get a config + tags: + - Configurations + description: |- + Returns configuration information for a single port of this NodeBalancer. - 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. + - __CLI__. - Notes: + ``` + linode-cli nodebalancers config-view + ``` - - 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. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - - 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). + - __OAuth__. - | 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*). | | + ``` + nodebalancers:read_only + ``` - #### OAuth Private Workflow - Additional Details + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers config-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested NodeBalancer config. + content: + application/json: + schema: + type: object + description: | + A NodeBalancer config represents the configuration of this NodeBalancer on a single port. For example, + a NodeBalancer Config on port 80 would typically represent how this + NodeBalancer response to HTTP requests. NodeBalancer configs have + a list of backends, called "nodes," that they forward requests between + based on their configuration. + x-akamai: + file-path: schemas/node-balancer-config.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This config's unique ID + example: 4567 + readOnly: true + x-linode-cli-display: 1 + algorithm: + type: string + description: | + What algorithm this NodeBalancer should use for routing traffic to backends. + example: roundrobin + default: roundrobin + enum: + - roundrobin + - leastconn + - source + x-linode-cli-display: 4 + check: + type: string + description: |- + The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. + + - If `none` no check is performed. + - `connection` requires only a connection to the backend to succeed. + - `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected. + example: http_body + default: none + enum: + - none + - connection + - http + - http_body + check_attempts: + type: integer + description: | + How many times to attempt a check before considering a backend to be down. + example: 3 + default: 3 + minimum: 1 + maximum: 30 + check_body: + type: string + description: | + This value must be present in the response body of the check in order for it to + pass. If this value is not present in the response body of a + check request, the backend is considered to be down. + example: it works + check_interval: + type: integer + description: |- + How often, in seconds, to check that backends are up and serving requests. - The following information expands on steps 5 through 7 of the private workflow: + Must be greater than `check_timeout`. + example: 90 + default: 31 + check_passive: + type: boolean + description: | + If true, any response from this backend with a `5xx` status code will be enough for + it to be considered unhealthy and taken out of rotation. + example: true + default: true + x-linode-cli-display: 6 + check_path: + type: string + description: | + The URL path to check on each backend. If the backend does not respond to this request + it is considered to be down. + example: /test + pattern: ^[a-zA-Z0-9\/\-%?&=.]*$ + check_timeout: + type: integer + description: |- + How long, in seconds, to wait for a check attempt before considering it failed. + + Must be less than `check_interval`. + example: 10 + default: 30 + minimum: 1 + maximum: 30 + cipher_suite: + type: string + description: |- + What ciphers to use for SSL connections served by this NodeBalancer. - 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: + - `legacy` is considered insecure and should only be used if necessary. + example: recommended + default: recommended + enum: + - recommended + - legacy + x-linode-cli-color: + default_: white + legacy: red + x-linode-cli-display: 7 + nodebalancer_id: + type: integer + description: | + __Read-only__ The ID for the NodeBalancer this config belongs to. + example: 12345 + readOnly: true + nodes_status: + type: object + description: | + __Read-only__ A structure containing information about the health of the backends for + this port. This information is updated periodically as checks + are performed against backends. + additionalProperties: false + readOnly: true + x-linode-cli-display: 10 + properties: + down: + type: integer + description: | + __Read-only__ The number of backends considered to be "DOWN" and unhealthy. These + are not in rotation, and not serving requests. + example: 0 + readOnly: true + up: + type: integer + description: | + __Read-only__ The number of backends considered to be "UP" and healthy, and + that are serving requests. + example: 4 + readOnly: true + port: + type: integer + description: | + The port this Config is for. These values must be unique across configs on a single + NodeBalancer (you can't have two configs for port 80, for example). While + some ports imply some protocols, no enforcement is done and + you may configure your NodeBalancer however is useful to you. + For example, while port 443 is generally used for HTTPS, you + do not need SSL configured to have a NodeBalancer listening + on port 443. + example: 80 + default: 80 + minimum: 1 + maximum: 65535 + x-linode-cli-display: 2 + protocol: + type: string + description: |- + The protocol this port is configured to serve. - ``` - https://login.linode.com/oauth/token - ``` + - The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`. - Make this request as `application/x-www-form-urlencoded` or as - `multipart/form-data` and include the following parameters in the POST body: + - The `https` protocol is mutually required with `ssl_cert` and `ssl_key`. - | 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. | + Review our guide on [Available Protocols](https://www.linode.com/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features. + example: http + default: http + enum: + - http + - https + - tcp + x-linode-cli-display: 3 + proxy_protocol: + type: string + description: |- + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. + + - If omitted, or set to `none`, the NodeBalancer doesn't send any auxiliary data over TCP connections. This is the default. + - If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol. + - If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol. + example: none + default: none + enum: + - none + - v1 + - v2 + ssl_cert: + type: string + description: |2- - You'll get a response like this: + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig's port. - ```json - { - "scope": "linodes:read_write", - "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c", - "refresh_token": "f2ec9712e616fdb5a2a21aa0e88cfadea7502ebc62cf5bd758dbcd65e1803bad", - "token_type": "bearer", - "expires_in": 7200 - } - ``` + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). - 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 + [Diffie-Hellman Parameters](https://www.linode.com/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy. - 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)). + The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `` will be printed where the field appears. - ## Rate Limiting + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-cert + ssl_commonname: + type: string + description: | + __Read-only__ The read-only common name automatically derived from the SSL certificate assigned + to this NodeBalancerConfig. Please refer to this field to verify + that the appropriate certificate is assigned to your NodeBalancerConfig. + example: www.example.com + readOnly: true + x-linode-cli-display: 8 + ssl_fingerprint: + type: string + description: | + __Read-only__ The read-only SHA1-encoded fingerprint automatically derived from the SSL + certificate assigned to this NodeBalancerConfig. Please refer + to this field to verify that the appropriate certificate is + assigned to your NodeBalancerConfig. + example: 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13 + readOnly: true + x-linode-cli-display: 9 + ssl_key: + type: string + description: |- + The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. - 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. + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). - 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. + The contents of this field will not be shown in any responses that display + the NodeBalancerConfig. Instead, `` will be printed where the field + appears. - ### Linode APIv4 Rate Limits + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig + response are automatically derived from your certificate. Please refer to these fields to + verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-key + stickiness: + type: string + description: |- + Controls how session stickiness is handled on this port. + + - If set to `none` connections will always be assigned a backend based on the algorithm configured. + - If set to `table` sessions from the same remote address will be routed to the same backend. + - For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer. + example: http_cookie + default: none + enum: + - none + - table + - http_cookie + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-node-balancer-config + security: + - personalAccessToken: [] + - oauth: + - nodebalancers:read_only + 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 + x-linode-cli-action: config-view + x-linode-grant: read_only + x-original-op-id: getNodeBalancerConfig + x-original-op-title: Config View + put: + operationId: put-node-balancer-config + summary: Update a config + tags: + - Configurations + description: |- + Updates the configuration for a single port on a NodeBalancer. - 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) + - __CLI__. - Creating Volumes has a dedicated rate limit of 25 requests per minute. That endpoint is: + ``` + linode-cli nodebalancers config-update + ``` - * [Volume Create](/docs/api/volumes/#volume-create) + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - Listing Images has a dedicated rate limit of 20 requests per minute. That endpoint is: + - __OAuth__. - * [Images List](/docs/api/images/#images-list) + ``` + nodebalancers:read_write + ``` - `/stats` endpoints have their own dedicated rate limits of 50 requests per minute. These endpoints are: + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers config-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The fields to update. + required: true + content: + application/json: + schema: + type: object + description: | + A NodeBalancer config represents the configuration of this NodeBalancer on a single port. For example, + a NodeBalancer Config on port 80 would typically represent how this + NodeBalancer response to HTTP requests. NodeBalancer configs have + a list of backends, called "nodes," that they forward requests between + based on their configuration. + x-akamai: + file-path: schemas/node-balancer-config.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This config's unique ID + example: '{{id}}' + readOnly: true + x-linode-cli-display: 1 + algorithm: + type: string + description: | + What algorithm this NodeBalancer should use for routing traffic to backends. + example: '{{algorithm}}' + default: roundrobin + enum: + - roundrobin + - leastconn + - source + x-linode-cli-display: 4 + check: + type: string + description: |- + The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. + + - If `none` no check is performed. + - `connection` requires only a connection to the backend to succeed. + - `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected. + example: '{{check}}' + default: none + enum: + - none + - connection + - http + - http_body + check_attempts: + type: integer + description: | + How many times to attempt a check before considering a backend to be down. + example: '{{check_attempts}}' + default: 3 + minimum: 1 + maximum: 30 + check_body: + type: string + description: | + This value must be present in the response body of the check in order for it to pass. If + this value is not present in the response body of a check request, + the backend is considered to be down. + example: '{{check_body}}' + check_interval: + type: integer + description: |- + How often, in seconds, to check that backends are up and serving requests. - * [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) + Must be greater than `check_timeout`. + example: '{{check_interval}}' + default: 31 + check_passive: + type: boolean + description: | + If true, any response from this backend with a `5xx` status code will be enough for + it to be considered unhealthy and taken out of rotation. + example: '{{check_passive}}' + default: true + x-linode-cli-display: 6 + check_path: + type: string + description: | + The URL path to check on each backend. If the backend does not respond to this request + it is considered to be down. + example: '{{check_path}}' + pattern: ^[a-zA-Z0-9\/\-%?&=.]*$ + check_timeout: + type: integer + description: |- + How long, in seconds, to wait for a check attempt before considering it failed. - Object Storage endpoints have a dedicated rate limit of 750 requests per second. The Object Storage endpoints are: + Must be less than `check_interval`. + example: '{{check_timeout}}' + default: 30 + minimum: 1 + maximum: 30 + cipher_suite: + type: string + description: |- + What ciphers to use for SSL connections served by this NodeBalancer. - * [Object Storage Endpoints](/docs/api/object-storage/) + - `legacy` is considered insecure and should only be used if necessary. + example: '{{cipher_suite}}' + default: recommended + enum: + - recommended + - legacy + x-linode-cli-color: + default_: white + legacy: red + x-linode-cli-display: 7 + nodebalancer_id: + type: integer + description: | + __Read-only__ The ID for the NodeBalancer this config belongs to. + example: '{{nodebalancer_id}}' + readOnly: true + nodes_status: + type: object + description: | + __Read-only__ A structure containing information about the health of the backends for this + port. This information is updated periodically as checks are + performed against backends. + additionalProperties: false + readOnly: true + properties: + down: + type: integer + description: | + __Read-only__ The number of backends considered to be "DOWN" and unhealthy. These + are not in rotation, and not serving requests. + example: 0 + readOnly: true + up: + type: integer + description: | + __Read-only__ The number of backends considered to be "UP" and healthy, and + that are serving requests. + example: 4 + readOnly: true + x-linode-cli-display: 10 + port: + type: integer + description: | + The port this Config is for. These values must be unique across configs on a single + NodeBalancer (you can't have two configs for port 80, for example). While + some ports imply some protocols, no enforcement is done and you + may configure your NodeBalancer however is useful to you. For + example, while port 443 is generally used for HTTPS, you do not + need SSL configured to have a NodeBalancer listening on port 443. + example: '{{port}}' + default: 80 + minimum: 1 + maximum: 65535 + x-linode-cli-display: 2 + protocol: + type: string + description: |- + The protocol this port is configured to serve. - Opening Support Tickets has a dedicated rate limit of 2 requests per minute. That endpoint is: + - The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`. - * [Open Support Ticket](/docs/api/support/#support-ticket-open) + - The `https` protocol is mutually required with `ssl_cert` and `ssl_key`. - Accepting Service Transfers has a dedicated rate limit of 2 requests per minute. That endpoint is: + Review our guide on [Available Protocols](https://www.linode.com/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features. + example: '{{protocol}}' + default: http + enum: + - http + - https + - tcp + x-linode-cli-display: 3 + proxy_protocol: + type: string + description: |- + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. + + - If omitted, or set to `none`, the NodeBalancer doesn't send any auxiliary data over TCP connections. This is the default. + - If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol. + - If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol. + example: '{{proxy_protocol}}' + default: none + enum: + - none + - v1 + - v2 + ssl_cert: + type: string + description: |2- - * [Service Transfer Accept](/docs/api/account/#service-transfer-accept) + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig's port. - ### Rate Limit HTTP Response Headers + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). - The Linode API includes the following HTTP response headers which are designed to help you avoid hitting rate limits which might disrupt your applications: + [Diffie-Hellman Parameters](https://www.linode.com/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy. - * **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. + The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `` will be printed where the field appears. - ## CLI (Command Line Interface) + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: '{{ssl_cert}}' + nullable: true + format: ssl-cert + ssl_commonname: + type: string + description: | + __Read-only__ The read-only common name automatically derived from the SSL certificate assigned + to this NodeBalancerConfig. Please refer to this field to verify + that the appropriate certificate is assigned to your NodeBalancerConfig. + example: '{{ssl_commonname}}' + readOnly: true + x-linode-cli-display: 8 + ssl_fingerprint: + type: string + description: | + __Read-only__ The read-only SHA1-encoded fingerprint automatically derived from the SSL certificate + assigned to this NodeBalancerConfig. Please refer to this field + to verify that the appropriate certificate is assigned to your + NodeBalancerConfig. + example: '{{ssl_fingerprint}}' + readOnly: true + x-linode-cli-display: 9 + ssl_key: + type: string + description: |- + The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. - 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. + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). - 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. + The contents of this field will not be shown in any responses that display + the NodeBalancerConfig. Instead, `` will be printed where the field + appears. - 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 + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig + response are automatically derived from your certificate. Please refer to these fields to + verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: '{{ssl_key}}' + nullable: true + format: ssl-key + stickiness: + type: string + description: |- + Controls how session stickiness is handled on this port. + + - If set to `none` connections will always be assigned a backend based on the algorithm configured. + - If set to `table` sessions from the same remote address will be routed to the same backend. + - For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer. + example: '{{stickiness}}' + default: none + enum: + - none + - table + - http_cookie + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Returns a single Account object. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Config updated successfully. + content: + application/json: + schema: + type: object + description: | + A NodeBalancer config represents the configuration of this NodeBalancer on a single port. For example, + a NodeBalancer Config on port 80 would typically represent how this + NodeBalancer response to HTTP requests. NodeBalancer configs have + a list of backends, called "nodes," that they forward requests between + based on their configuration. + x-akamai: + file-path: schemas/node-balancer-config.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This config's unique ID + example: 4567 + readOnly: true + x-linode-cli-display: 1 + algorithm: + type: string + description: | + What algorithm this NodeBalancer should use for routing traffic to backends. + example: roundrobin + default: roundrobin + enum: + - roundrobin + - leastconn + - source + x-linode-cli-display: 4 + check: + type: string + description: |- + The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. + + - If `none` no check is performed. + - `connection` requires only a connection to the backend to succeed. + - `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected. + example: http_body + default: none + enum: + - none + - connection + - http + - http_body + check_attempts: + type: integer + description: | + How many times to attempt a check before considering a backend to be down. + example: 3 + default: 3 + minimum: 1 + maximum: 30 + check_body: + type: string + description: | + This value must be present in the response body of the check in order for it to + pass. If this value is not present in the response body of a + check request, the backend is considered to be down. + example: it works + check_interval: + type: integer + description: |- + How often, in seconds, to check that backends are up and serving requests. + + Must be greater than `check_timeout`. + example: 90 + default: 31 + check_passive: + type: boolean + description: | + If true, any response from this backend with a `5xx` status code will be enough for + it to be considered unhealthy and taken out of rotation. + example: true + default: true + x-linode-cli-display: 6 + check_path: + type: string + description: | + The URL path to check on each backend. If the backend does not respond to this request + it is considered to be down. + example: /test + pattern: ^[a-zA-Z0-9\/\-%?&=.]*$ + check_timeout: + type: integer + description: |- + How long, in seconds, to wait for a check attempt before considering it failed. + + Must be less than `check_interval`. + example: 10 + default: 30 + minimum: 1 + maximum: 30 + cipher_suite: + type: string + description: |- + What ciphers to use for SSL connections served by this NodeBalancer. + + - `legacy` is considered insecure and should only be used if necessary. + example: recommended + default: recommended + enum: + - recommended + - legacy + x-linode-cli-color: + default_: white + legacy: red + x-linode-cli-display: 7 + nodebalancer_id: + type: integer + description: | + __Read-only__ The ID for the NodeBalancer this config belongs to. + example: 12345 + readOnly: true + nodes_status: + type: object + description: | + __Read-only__ A structure containing information about the health of the backends for + this port. This information is updated periodically as checks + are performed against backends. + additionalProperties: false + readOnly: true + properties: + down: + type: integer + description: | + __Read-only__ The number of backends considered to be "DOWN" and unhealthy. These + are not in rotation, and not serving requests. + example: 0 + readOnly: true + up: + type: integer + description: | + __Read-only__ The number of backends considered to be "UP" and healthy, and + that are serving requests. + example: 4 + readOnly: true + x-linode-cli-display: 10 + port: + type: integer + description: | + The port this Config is for. These values must be unique across configs on a single + NodeBalancer (you can't have two configs for port 80, for example). While + some ports imply some protocols, no enforcement is done and + you may configure your NodeBalancer however is useful to you. + For example, while port 443 is generally used for HTTPS, you + do not need SSL configured to have a NodeBalancer listening + on port 443. + example: 80 + default: 80 + minimum: 1 + maximum: 65535 + x-linode-cli-display: 2 + protocol: + type: string + description: |- + The protocol this port is configured to serve. + + - The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`. - **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. + - The `https` protocol is mutually required with `ssl_cert` and `ssl_key`. - **Parent and child accounts** + Review our guide on [Available Protocols](https://www.linode.com/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features. + example: http + default: http + enum: + - http + - https + - tcp + x-linode-cli-display: 3 + proxy_protocol: + type: string + description: |- + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. + + - If omitted, or set to `none`, the NodeBalancer doesn't send any auxiliary data over TCP connections. This is the default. + - If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol. + - If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol. + example: none + default: none + enum: + - none + - v1 + - v2 + ssl_cert: + type: string + description: |2- - 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. + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig's port. - * 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 + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + [Diffie-Hellman Parameters](https://www.linode.com/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy. + + The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `` will be printed where the field appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-cert + ssl_commonname: + type: string + description: | + __Read-only__ The read-only common name automatically derived from the SSL certificate assigned + to this NodeBalancerConfig. Please refer to this field to verify + that the appropriate certificate is assigned to your NodeBalancerConfig. + example: www.example.com + readOnly: true + x-linode-cli-display: 8 + ssl_fingerprint: + type: string + description: | + __Read-only__ The read-only SHA1-encoded fingerprint automatically derived from the SSL + certificate assigned to this NodeBalancerConfig. Please refer + to this field to verify that the appropriate certificate is + assigned to your NodeBalancerConfig. + example: 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13 + readOnly: true + x-linode-cli-display: 9 + ssl_key: + type: string + description: |- + The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. + + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + The contents of this field will not be shown in any responses that display + the NodeBalancerConfig. Instead, `` will be printed where the field + appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig + response are automatically derived from your certificate. Please refer to these fields to + verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-key + stickiness: + type: string + description: |- + Controls how session stickiness is handled on this port. + + - If set to `none` connections will always be assigned a backend based on the algorithm configured. + - If set to `table` sessions from the same remote address will be routed to the same backend. + - For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer. + example: http_cookie + default: none + enum: + - none + - table + - http_cookie + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-node-balancer-config 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' + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > + 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" + "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/account + https://api.linode.com/v4/nodebalancers/12345/configs/4567 - 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: + 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 + x-linode-cli-action: config-update + x-linode-grant: read_write + x-original-op-id: updateNodeBalancerConfig + x-original-op-title: Config Update + delete: + operationId: delete-node-balancer-config + summary: Delete a config 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. + - Configurations + description: |- + Deletes the Config for a port of this NodeBalancer. - **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 + __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. + + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers config-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers config-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': + default: description: | - List of regions and the services available in each. + Error 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' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + NodeBalancer Config deleted successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-node-balancer-config + security: + - personalAccessToken: [] + - oauth: + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > - curl https://api.linode.com/v4/account/availability \ - -H "Authorization: Bearer $TOKEN" + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + -X DELETE \ + https://api.linode.com/v4/nodebalancers/12345/configs/4567 - 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 + source: |- + linode-cli nodebalancers config-delete \ + 12345 4567 + x-linode-cli-action: config-delete + x-linode-grant: read_write + x-original-op-id: deleteNodeBalancerConfig + x-original-op-title: Config Delete + x-linode-cli-command: nodebalancers + /nodebalancers/{nodeBalancerId}/configs/{configId}/nodes: + x-akamai: + file-path: paths/nodes.yaml + path-info: /nodebalancers/{nodeBalancerId}/configs/{configId}/nodes + parameters: + - name: nodeBalancerId + in: path 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' + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml + required: true + schema: + type: integer + - name: configId + in: path 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 + The ID of the NodeBalancer config to access. + example: '{{configId}}' + x-akamai: + file-path: parameters/config-id-node-balancer.yaml + required: true + schema: + type: integer post: + operationId: post-node-balancer-node + summary: Create a node 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. + - Nodes + 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. - 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. + - __CLI__. - **Parent and child accounts** + ``` + linode-cli nodebalancers node-create + ``` - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - * A child account user can't cancel a child account. + - __OAuth__. - * You can't cancel a parent account if it has an active child account. + ``` + nodebalancers:read_write + ``` - * 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers node-create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: > - Supply a comment stating the reason that you are cancelling your account. + description: | + Information about the Node to create. 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 + required: + - label + - address + allOf: + - type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single port of a NodeBalancer. Nodes + are specific to NodeBalancer Configs, and serve traffic over their + private IP. If the same Linode is serving traffic for more than + one port on the same NodeBalancer, one NodeBalancer Node is required + for each config (port) it should serve requests on. For example, + if you have four backends, and each should response to both HTTP + and HTTPS requests, you will need two NodeBalancerConfigs (port + 80 and port 443) and four backends each - one for each of the Linodes + serving requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false properties: - survey_link: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: 54321 + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ be a private + IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: 4567 + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: 12345 + readOnly: true + status: 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 + description: | + __Read-only__ The current status of this node, based on the configured checks of its NodeBalancer + Config. + example: UP + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single backend + yet. Nodes with a higher weight will receive more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: errors: type: array items: type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname 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' + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Node created successfully. + content: + application/json: + schema: + type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single port of a NodeBalancer. Nodes + are specific to NodeBalancer Configs, and serve traffic over their + private IP. If the same Linode is serving traffic for more than + one port on the same NodeBalancer, one NodeBalancer Node is required + for each config (port) it should serve requests on. For example, + if you have four backends, and each should response to both HTTP + and HTTPS requests, you will need two NodeBalancerConfigs (port + 80 and port 443) and four backends each - one for each of the Linodes + serving requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: 54321 + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ be a private + IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: 4567 + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: 12345 + readOnly: true + status: + type: string + description: | + __Read-only__ The current status of this node, based on the configured checks of its NodeBalancer + Config. + example: UP + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single backend + yet. Nodes with a higher weight will receive more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-node-balancer-node + security: + - personalAccessToken: [] + - oauth: + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > + source: |- curl -H "Content-Type: application/json" \ -H "Authorization: Bearer $TOKEN" \ -X POST -d '{ - "comments": "I am consolidating my accounts." + "address": "192.168.210.120:80", + "label": "node54321", + "weight": 50, + "mode": "accept" }' \ - https://api.linode.com/v4/account/cancel + https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes - 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' + source: |- + linode-cli nodebalancers node-create \ + 12345 4567 \ + --address 192.168.210.120:80 \ + --label node54321 \ + --weight 50 \ + --mode accept + x-linode-cli-action: node-create + x-linode-grant: read_write + x-original-op-id: createNodeBalancerNode + x-original-op-title: Node Create + get: + operationId: get-node-balancer-config-nodes + summary: List nodes 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. + - Nodes + description: |- + Returns a paginated list of NodeBalancer nodes associated with this Config. These are the backends that will be sent traffic for this port. - **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 + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers nodes-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers nodes-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} responses: - '200': - description: Returns child-level accounts. + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of NodeBalancer nodes. content: application/json: schema: type: object + additionalProperties: false properties: data: type: array items: - $ref: '#/components/schemas/ChildAccount' + type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single + port of a NodeBalancer. Nodes are specific to NodeBalancer + Configs, and serve traffic over their private IP. If the + same Linode is serving traffic for more than one port on the + same NodeBalancer, one NodeBalancer Node is required for each + config (port) it should serve requests on. For example, if + you have four backends, and each should response to both HTTP + and HTTPS requests, you will need two NodeBalancerConfigs + (port 80 and port 443) and four backends each - one for each + of the Linodes serving requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: 54321 + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ + be a private IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: 4567 + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: 12345 + readOnly: true + status: + type: string + description: | + __Read-only__ The current status of this node, based on the configured + checks of its NodeBalancer Config. + example: UP + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single + backend yet. Nodes with a higher weight will receive + more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 page: - $ref: '#/components/schemas/PaginationEnvelope/properties/page' + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true pages: - $ref: '#/components/schemas/PaginationEnvelope/properties/pages' + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true 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 + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-node-balancer-config-nodes 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' + - nodebalancers:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/account/child-accounts/A1BC2DEF-34GH-567I-J890KLMN12O34P56 + https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes - lang: CLI - source: > - linode-cli child-account view A1BC2DEF-34GH-567I-J890KLMN12O34P56 - /account/child-accounts/{euuid}/token: - x-linode-cli-command: child-account + source: linode-cli nodebalancers nodes-list 12345 4567 + x-linode-cli-action: nodes-list + x-linode-grant: read_only + x-original-op-id: getNodeBalancerConfigNodes + x-original-op-title: Nodes List + x-linode-cli-command: nodebalancers + /nodebalancers/{nodeBalancerId}/configs/{configId}/nodes/{nodeId}: + x-akamai: + file-path: paths/config-node.yaml + path-info: /nodebalancers/{nodeBalancerId}/configs/{configId}/nodes/{nodeId} 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 + - name: nodeBalancerId + in: path 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: + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml + required: true + schema: + type: integer + - name: configId + in: path + description: | + The ID of the Config to access + example: '{{configId}}' + x-akamai: + file-path: parameters/config-id.yaml + required: true + schema: + type: integer + - name: nodeId + in: path + description: | + The ID of the Node to access + example: '{{nodeId}}' + x-akamai: + file-path: parameters/node-id.yaml + required: true + schema: + type: integer + get: + operationId: get-node-balancer-node + summary: Get a node balancer's node + tags: + - Nodes + description: |- + Returns information about a single Node, a backend for this NodeBalancer's configured port. - _ - **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: + - __CLI__. - * 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. + ``` + linode-cli nodebalancers node-view + ``` - * The created token inherits the permissions of the proxy user. It will never have less. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - * The API returns the raw token in the response. You can't get it again, so be sure to store it. + - __OAuth__. - Example workflow: + ``` + nodebalancers:read_write + ``` - 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers node-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Token created successfully. + default: + description: | + Error content: application/json: schema: - $ref: '#/components/schemas/ProxyUserToken' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of NodeBalancer nodes. + content: + application/json: + schema: + type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single port of a NodeBalancer. Nodes + are specific to NodeBalancer Configs, and serve traffic over their + private IP. If the same Linode is serving traffic for more than + one port on the same NodeBalancer, one NodeBalancer Node is required + for each config (port) it should serve requests on. For example, + if you have four backends, and each should response to both HTTP + and HTTPS requests, you will need two NodeBalancerConfigs (port + 80 and port 443) and four backends each - one for each of the Linodes + serving requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: 54321 + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ be a private + IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: 4567 + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: 12345 + readOnly: true + status: + type: string + description: | + __Read-only__ The current status of this node, based on the configured checks of its NodeBalancer + Config. + example: UP + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single backend + yet. Nodes with a higher weight will receive more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-node-balancer-node + security: + - personalAccessToken: [] + - oauth: + - nodebalancers:read_write 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 + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes/54321 - 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 + source: linode-cli nodebalancers node-view 12345 4567 54321 + x-linode-cli-action: node-view + x-linode-grant: read_only + x-original-op-id: getNodeBalancerNode + x-original-op-title: Node View + put: + operationId: put-node-balancer-node + summary: Update a node tags: - - Account - summary: Credit Card Add/Edit - description: | - **DEPRECATED**. Please use Payment Method Add ([POST /account/payment-methods](/docs/api/account/#payment-method-add)). + - Nodes + description: |- + Updates information about a Node, a backend for this NodeBalancer's configured port. - 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 + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers node-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers node-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Update the credit card information associated with your Account. + description: | + The fields to update. 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 + type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single port of a NodeBalancer. Nodes + are specific to NodeBalancer Configs, and serve traffic over their + private IP. If the same Linode is serving traffic for more than one + port on the same NodeBalancer, one NodeBalancer Node is required for + each config (port) it should serve requests on. For example, if you + have four backends, and each should response to both HTTP and HTTPS + requests, you will need two NodeBalancerConfigs (port 80 and port + 443) and four backends each - one for each of the Linodes serving + requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: '{{id}}' + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ be a private IP + address. + example: '{{address}}' + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: '{{config_id}}' + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: '{{label}}' + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: '{{mode}}' + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: '{{nodebalancer_id}}' + readOnly: true + status: + type: string + description: | + __Read-only__ The current status of this node, based on the configured checks of its NodeBalancer + Config. + example: '{{status}}' + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single backend yet. Nodes + with a higher weight will receive more traffic. + example: '{{weight}}' + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json 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. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Node updated successfully. 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 + type: object + description: | + A NodeBalancerNode represents a single backend serving requests for a single port of a NodeBalancer. Nodes + are specific to NodeBalancer Configs, and serve traffic over their + private IP. If the same Linode is serving traffic for more than + one port on the same NodeBalancer, one NodeBalancer Node is required + for each config (port) it should serve requests on. For example, + if you have four backends, and each should response to both HTTP + and HTTPS requests, you will need two NodeBalancerConfigs (port + 80 and port 443) and four backends each - one for each of the Linodes + serving requests for that port. + x-akamai: + file-path: schemas/node-balancer-node.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This node's unique ID. + example: 54321 + readOnly: true + x-linode-cli-display: 1 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ be a private + IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + config_id: + type: integer + description: | + __Read-only__ The NodeBalancer Config ID that this Node belongs to. + example: 4567 + readOnly: true + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + nodebalancer_id: + type: integer + description: | + __Read-only__ The NodeBalancer ID that this Node belongs to. + example: 12345 + readOnly: true + status: + type: string + description: | + __Read-only__ The current status of this node, based on the configured checks of its NodeBalancer + Config. + example: UP + readOnly: true + enum: + - unknown + - UP + - DOWN + x-linode-cli-color: + DOWN: red + UP: green + default_: white + unknown: yellow + x-linode-cli-display: 4 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single backend + yet. Nodes with a higher weight will receive more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-node-balancer-node 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' + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/account/entity-transfers/123E4567-E89B-12D3-A456-426614174000 + 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 + x-linode-cli-action: node-update + x-linode-grant: read_write + x-original-op-id: updateNodeBalancerNode + x-original-op-title: Node Update delete: - deprecated: true - x-linode-grant: unrestricted only - x-linode-cli-skip: true + operationId: delete-node-balancer-config-node + summary: Delete a node balancer's node 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 + - Nodes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers node-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers node-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: > - Entity Transfer canceled. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Node deleted successfully. content: application/json: schema: type: object - default: - $ref: '#/components/responses/ErrorResponse' + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-node-balancer-config-node + security: + - personalAccessToken: [] + - oauth: + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > + 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 + -X DELETE \ + https://api.linode.com/v4/nodebalancers/12345/configs/4567/nodes/54321 - lang: CLI - source: > - linode-cli events view 123 - /account/events/{eventId}/read: - x-linode-cli-command: events + source: |- + linode-cli nodebalancers node-delete \ + 12345 4567 54321 + x-linode-cli-action: node-delete + x-linode-grant: read_write + x-original-op-id: deleteNodeBalancerConfigNode + x-original-op-title: Node Delete + x-linode-cli-command: nodebalancers + /nodebalancers/{nodeBalancerId}/configs/{configId}/rebuild: + x-akamai: + file-path: paths/config-rebuild.yaml + path-info: /nodebalancers/{nodeBalancerId}/configs/{configId}/rebuild parameters: - - name: eventId - in: path - description: The ID of the Event to designate as read. - required: true - schema: - type: integer + - name: nodeBalancerId + in: path + description: | + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml + required: true + schema: + type: integer + - name: configId + in: path + description: | + The ID of the Config to access + example: '{{configId}}' + x-akamai: + file-path: parameters/config-id.yaml + required: true + schema: + type: integer post: - x-linode-grant: read_only + operationId: post-rebuild-node-balancer-config + summary: Rebuild a config 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. + - Configurations + description: |- + Rebuilds a NodeBalancer Config and its Nodes that you have permission to modify. + + Use this operation to update a NodeBalancer's Config and Nodes with a single request. + + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers config-rebuild + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers config-rebuild + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Information about the NodeBalancer Config to rebuild. 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 + content: + application/json: + schema: + allOf: + - type: object + description: | + A NodeBalancer config represents the configuration of this NodeBalancer on a single port. For example, + a NodeBalancer Config on port 80 would typically represent how this + NodeBalancer response to HTTP requests. NodeBalancer configs have + a list of backends, called "nodes," that they forward requests between + based on their configuration. + x-akamai: + file-path: schemas/node-balancer-config.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This config's unique ID + example: 4567 + readOnly: true + x-linode-cli-display: 1 + algorithm: + type: string + description: | + What algorithm this NodeBalancer should use for routing traffic to backends. + example: roundrobin + default: roundrobin + enum: + - roundrobin + - leastconn + - source + x-linode-cli-display: 4 + check: + type: string + description: |- + The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. + + - If `none` no check is performed. + - `connection` requires only a connection to the backend to succeed. + - `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected. + example: http_body + default: none + enum: + - none + - connection + - http + - http_body + check_attempts: + type: integer + description: | + How many times to attempt a check before considering a backend to be down. + example: 3 + default: 3 + minimum: 1 + maximum: 30 + check_body: + type: string + description: | + This value must be present in the response body of the check in order for it to + pass. If this value is not present in the response body of a + check request, the backend is considered to be down. + example: it works + check_interval: + type: integer + description: |- + How often, in seconds, to check that backends are up and serving requests. + + Must be greater than `check_timeout`. + example: 90 + default: 31 + check_passive: + type: boolean + description: | + If true, any response from this backend with a `5xx` status code will be enough for + it to be considered unhealthy and taken out of rotation. + example: true + default: true + x-linode-cli-display: 6 + check_path: + type: string + description: | + The URL path to check on each backend. If the backend does not respond to this request + it is considered to be down. + example: /test + pattern: ^[a-zA-Z0-9\/\-%?&=.]*$ + check_timeout: + type: integer + description: |- + How long, in seconds, to wait for a check attempt before considering it failed. + + Must be less than `check_interval`. + example: 10 + default: 30 + minimum: 1 + maximum: 30 + cipher_suite: + type: string + description: |- + What ciphers to use for SSL connections served by this NodeBalancer. + + - `legacy` is considered insecure and should only be used if necessary. + example: recommended + default: recommended + enum: + - recommended + - legacy + x-linode-cli-color: + default_: white + legacy: red + x-linode-cli-display: 7 + nodebalancer_id: + type: integer + description: | + __Read-only__ The ID for the NodeBalancer this config belongs to. + example: 12345 + readOnly: true + nodes_status: + type: object + description: | + __Read-only__ A structure containing information about the health of the backends for + this port. This information is updated periodically as checks + are performed against backends. + additionalProperties: false + readOnly: true + properties: + down: + type: integer + description: | + __Read-only__ The number of backends considered to be "DOWN" and unhealthy. These + are not in rotation, and not serving requests. + example: 0 + readOnly: true + up: + type: integer + description: | + __Read-only__ The number of backends considered to be "UP" and healthy, and + that are serving requests. + example: 4 + readOnly: true + x-linode-cli-display: 10 + port: + type: integer + description: | + The port this Config is for. These values must be unique across configs on a single + NodeBalancer (you can't have two configs for port 80, for example). While + some ports imply some protocols, no enforcement is done and + you may configure your NodeBalancer however is useful to you. + For example, while port 443 is generally used for HTTPS, you + do not need SSL configured to have a NodeBalancer listening + on port 443. + example: 80 + default: 80 + minimum: 1 + maximum: 65535 + x-linode-cli-display: 2 + protocol: + type: string + description: |- + The protocol this port is configured to serve. + + - The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`. + + - The `https` protocol is mutually required with `ssl_cert` and `ssl_key`. + + Review our guide on [Available Protocols](https://www.linode.com/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features. + example: http + default: http + enum: + - http + - https + - tcp + x-linode-cli-display: 3 + proxy_protocol: + type: string + description: |- + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. + + - If omitted, or set to `none`, the NodeBalancer doesn't send any auxiliary data over TCP connections. This is the default. + - If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol. + - If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol. + example: none + default: none + enum: + - none + - v1 + - v2 + ssl_cert: + type: string + description: |2- + + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig's port. + + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + [Diffie-Hellman Parameters](https://www.linode.com/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy. + + The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `` will be printed where the field appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-cert + ssl_commonname: + type: string + description: | + __Read-only__ The read-only common name automatically derived from the SSL certificate assigned + to this NodeBalancerConfig. Please refer to this field to verify + that the appropriate certificate is assigned to your NodeBalancerConfig. + example: www.example.com + readOnly: true + x-linode-cli-display: 8 + ssl_fingerprint: + type: string + description: | + __Read-only__ The read-only SHA1-encoded fingerprint automatically derived from the SSL + certificate assigned to this NodeBalancerConfig. Please refer + to this field to verify that the appropriate certificate is + assigned to your NodeBalancerConfig. + example: 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13 + readOnly: true + x-linode-cli-display: 9 + ssl_key: + type: string + description: |- + The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. + + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + The contents of this field will not be shown in any responses that display + the NodeBalancerConfig. Instead, `` will be printed where the field + appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig + response are automatically derived from your certificate. Please refer to these fields to + verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-key + stickiness: + type: string + description: |- + Controls how session stickiness is handled on this port. + + - If set to `none` connections will always be assigned a backend based on the algorithm configured. + - If set to `table` sessions from the same remote address will be routed to the same backend. + - For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer. + example: http_cookie + default: none + enum: + - none + - table + - http_cookie + x-linode-cli-display: 5 + - type: object + additionalProperties: false + 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. + additionalProperties: false + properties: + id: + type: integer + description: | + The unique ID of the Node to update. + example: 54321 + address: + type: string + description: | + The private IP Address where this backend can be reached. This _must_ + be a private IP address. + example: 192.168.210.120:80 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: | + The label for this node. This is for display purposes only. + example: node54321 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_.]{3,32}' + x-linode-cli-display: 2 + mode: + type: string + description: |- + The mode this NodeBalancer should use when sending traffic to this backend. + + - If set to `accept` this backend is accepting traffic. + - If set to `reject` this backend will not receive traffic. + - If set to `drain` this backend will not receive _new_ traffic, but connections already pinned to it will continue to be routed to it. + - If set to `backup`, this backend will only receive traffic if all `accept` nodes are down. + example: accept + enum: + - accept + - reject + - drain + - backup + x-linode-cli-display: 6 + weight: + type: integer + description: | + Used when picking a backend to serve a request and is not pinned to a single + backend yet. Nodes with a higher weight will receive + more traffic. + example: 50 + minimum: 1 + maximum: 255 + x-linode-cli-display: 5 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json 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. + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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 + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + NodeBalancer created successfully. content: application/json: schema: type: object + description: | + A NodeBalancer config represents the configuration of this NodeBalancer on a single port. For example, + a NodeBalancer Config on port 80 would typically represent how this + NodeBalancer response to HTTP requests. NodeBalancer configs have + a list of backends, called "nodes," that they forward requests between + based on their configuration. + x-akamai: + file-path: schemas/node-balancer-config.yaml + additionalProperties: false 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 + id: + type: integer + description: | + __Read-only__ This config's unique ID + example: 4567 + readOnly: true + x-linode-cli-display: 1 + algorithm: + type: string + description: | + What algorithm this NodeBalancer should use for routing traffic to backends. + example: roundrobin + default: roundrobin + enum: + - roundrobin + - leastconn + - source + x-linode-cli-display: 4 + check: + type: string + description: |- + The type of check to perform against backends to ensure they are serving requests. This is used to determine if backends are up or down. + + - If `none` no check is performed. + - `connection` requires only a connection to the backend to succeed. + - `http` and `http_body` rely on the backend serving HTTP, and that the response returned matches what is expected. + example: http_body + default: none + enum: + - none + - connection + - http + - http_body + check_attempts: + type: integer + description: | + How many times to attempt a check before considering a backend to be down. + example: 3 + default: 3 + minimum: 1 + maximum: 30 + check_body: + type: string + description: | + This value must be present in the response body of the check in order for it to + pass. If this value is not present in the response body of a + check request, the backend is considered to be down. + example: it works + check_interval: + type: integer + description: |- + How often, in seconds, to check that backends are up and serving requests. + + Must be greater than `check_timeout`. + example: 90 + default: 31 + check_passive: + type: boolean + description: | + If true, any response from this backend with a `5xx` status code will be enough for + it to be considered unhealthy and taken out of rotation. + example: true + default: true + x-linode-cli-display: 6 + check_path: + type: string + description: | + The URL path to check on each backend. If the backend does not respond to this request + it is considered to be down. + example: /test + pattern: ^[a-zA-Z0-9\/\-%?&=.]*$ + check_timeout: + type: integer + description: |- + How long, in seconds, to wait for a check attempt before considering it failed. + + Must be less than `check_interval`. + example: 10 + default: 30 + minimum: 1 + maximum: 30 + cipher_suite: + type: string + description: |- + What ciphers to use for SSL connections served by this NodeBalancer. + + - `legacy` is considered insecure and should only be used if necessary. + example: recommended + default: recommended + enum: + - recommended + - legacy + x-linode-cli-color: + default_: white + legacy: red + x-linode-cli-display: 7 + nodebalancer_id: + type: integer + description: | + __Read-only__ The ID for the NodeBalancer this config belongs to. + example: 12345 + readOnly: true + nodes_status: + type: object + description: | + __Read-only__ A structure containing information about the health of the backends for + this port. This information is updated periodically as checks + are performed against backends. + additionalProperties: false + readOnly: true + properties: + down: + type: integer + description: | + __Read-only__ The number of backends considered to be "DOWN" and unhealthy. These + are not in rotation, and not serving requests. + example: 0 + readOnly: true + up: + type: integer + description: | + __Read-only__ The number of backends considered to be "UP" and healthy, and + that are serving requests. + example: 4 + readOnly: true + x-linode-cli-display: 10 + port: + type: integer + description: | + The port this Config is for. These values must be unique across configs on a single + NodeBalancer (you can't have two configs for port 80, for example). While + some ports imply some protocols, no enforcement is done and + you may configure your NodeBalancer however is useful to you. + For example, while port 443 is generally used for HTTPS, you + do not need SSL configured to have a NodeBalancer listening + on port 443. + example: 80 + default: 80 + minimum: 1 + maximum: 65535 + x-linode-cli-display: 2 + protocol: + type: string + description: |- + The protocol this port is configured to serve. + + - The `http` and `tcp` protocols do not support `ssl_cert` and `ssl_key`. + + - The `https` protocol is mutually required with `ssl_cert` and `ssl_key`. + + Review our guide on [Available Protocols](https://www.linode.com/docs/products/networking/nodebalancers/guides/protocols/) for information on protocol features. + example: http + default: http + enum: + - http + - https + - tcp + x-linode-cli-display: 3 + proxy_protocol: + type: string + description: |- + ProxyProtocol is a TCP extension that sends initial TCP connection information such as source/destination IPs and ports to backend devices. This information would be lost otherwise. Backend devices must be configured to work with ProxyProtocol if enabled. + + - If omitted, or set to `none`, the NodeBalancer doesn't send any auxiliary data over TCP connections. This is the default. + - If set to `v1`, the human-readable header format (Version 1) is used. Requires `tcp` protocol. + - If set to `v2`, the binary header format (Version 2) is used. Requires `tcp` protocol. + example: none + default: none + enum: + - none + - v1 + - v2 + ssl_cert: + type: string + description: |2- + + The PEM-formatted public SSL certificate (or the combined PEM-formatted SSL certificate and Certificate Authority chain) that should be served on this NodeBalancerConfig's port. + + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + [Diffie-Hellman Parameters](https://www.linode.com/docs/products/networking/nodebalancers/guides/ssl-termination/#diffie-hellman-parameters) can be included in this value to enable forward secrecy. + + The contents of this field will not be shown in any responses that display the NodeBalancerConfig. Instead, `` will be printed where the field appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig response are automatically derived from your certificate. Please refer to these fields to verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-cert + ssl_commonname: + type: string + description: | + __Read-only__ The read-only common name automatically derived from the SSL certificate assigned + to this NodeBalancerConfig. Please refer to this field to verify + that the appropriate certificate is assigned to your NodeBalancerConfig. + example: www.example.com + readOnly: true + x-linode-cli-display: 8 + ssl_fingerprint: + type: string + description: | + __Read-only__ The read-only SHA1-encoded fingerprint automatically derived from the SSL + certificate assigned to this NodeBalancerConfig. Please refer + to this field to verify that the appropriate certificate is + assigned to your NodeBalancerConfig. + example: 00:01:02:03:04:05:06:07:08:09:0A:0B:0C:0D:0E:0F:10:11:12:13 + readOnly: true + x-linode-cli-display: 9 + ssl_key: + type: string + description: |- + The PEM-formatted private key for the SSL certificate set in the `ssl_cert` field. + + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI). + + The contents of this field will not be shown in any responses that display + the NodeBalancerConfig. Instead, `` will be printed where the field + appears. + + The read-only `ssl_commonname` and `ssl_fingerprint` fields in a NodeBalancerConfig + response are automatically derived from your certificate. Please refer to these fields to + verify that the appropriate certificate was assigned to your NodeBalancerConfig. + example: + nullable: true + format: ssl-key + stickiness: + type: string + description: |- + Controls how session stickiness is handled on this port. + + - If set to `none` connections will always be assigned a backend based on the algorithm configured. + - If set to `table` sessions from the same remote address will be routed to the same backend. + - For HTTP or HTTPS clients, `http_cookie` allows sessions to be routed to the same backend based on a cookie set by the NodeBalancer. + example: http_cookie + default: none + enum: + - none + - table + - http_cookie + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-rebuild-node-balancer-config 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' + - nodebalancers:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/account/logins + 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 account logins-list - /account/logins/{loginId}: + 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"}' + x-linode-cli-action: config-rebuild + x-linode-grant: add_nodebalancers + x-original-op-id: rebuildNodeBalancerConfig + x-original-op-title: Config Rebuild + x-linode-cli-command: nodebalancers + /nodebalancers/{nodeBalancerId}/firewalls: + x-akamai: + file-path: paths/node-balancer-firewalls.yaml + path-info: /nodebalancers/{nodeBalancerId}/firewalls parameters: - - name: loginId + - name: nodeBalancerId in: path - description: The ID of the login object to access. + description: | + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml required: true schema: type: integer - x-linode-cli-command: account get: + operationId: get-node-balancer-firewalls + summary: List node balancer firewalls 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 + - Firewalls + description: |- + View information for Firewalls assigned to this NodeBalancer. + + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers firewalls + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers firewalls + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} 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. + default: + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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 + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of Firewalls assigned to this NodeBalancer. + content: + application/json: + schema: + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - type: object + properties: + data: + type: array + items: + type: object + description: | + A resource that controls incoming and outgoing network traffic to a compute + service. Only one enabled Firewall can be attached to a + particular service at any given time. [Create a firewall + device](https://techdocs.akamai.com/linode-api/reference/post-firewall-device) + to assign a Firewall to a service. Currently, Firewalls + can assigned to Linode compute instances and NodeBalancers. + x-akamai: + file-path: schemas/firewall.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The Firewall's unique ID. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + tags: + type: array + description: | + An array of tags applied to this object. Tags are for organizational + purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Firewall was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + label: + type: string + description: |- + The Firewall's label, for display purposes only. + + Firewall labels have the following constraints: + + - Must begin and end with an alphanumeric character. + - May only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + - Cannot have two hyphens (`--`), underscores (`__`) or periods (`..`) in a row. + - Must be between 3 and 32 characters. + - Must be unique. + example: firewall123 + minLength: 3 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + rules: + type: object + description: |- + The inbound and outbound access rules to apply to the Firewall. + + A Firewall may have up to 25 rules across its inbound and outbound rulesets. + + Multiple rules are applied in order. If two rules conflict, the first rule takes precedence. For example, if the first rule accepts inbound traffic from an address, and the second rule drops inbound traffic the same address, the first rule applies and inbound traffic from that address is accepted. + additionalProperties: false + properties: + inbound: + type: array + description: | + The inbound rules for the firewall, as a JSON array. + items: + type: object + description: | + One of a Firewall's inbound or outbound access rules. + The `ports` property can be used to allow traffic + on a comma-separated list of different ports. + x-akamai: + file-path: schemas/firewall-rule-config.yaml + additionalProperties: false + properties: + description: + type: string + description: | + Used to describe this rule. For display purposes + only. + example: An example firewall rule description. + minLength: 1 + maxLength: 100 + action: + type: string + description: | + Controls whether traffic is accepted or dropped by + this rule. Overrides the Firewall's `inbound_policy` + if this is an inbound rule, or the `outbound_policy` + if this is an outbound rule. + example: ACCEPT + enum: + - ACCEPT + - DROP + addresses: + type: object + description: |- + The IPv4 and/or IPv6 addresses affected by this rule. A Rule can have up to 255 total addresses or networks listed across its IPv4 and IPv6 arrays. A network and a single IP are treated as equivalent when accounting for this limit. + + Must contain `ipv4`, `ipv6`, or both. + additionalProperties: false + properties: + ipv4: + type: array + description: |- + A list of IPv4 addresses or networks. Addresses must be in IP/mask format. Must not be an empty list. + + If "0.0.0.0/0" is included in this list, all IPv4 addresses are affected by this rule. + example: + - 192.0.2.0/24 + - 198.51.100.2/32 + items: + type: string + ipv6: + type: array + description: |- + A list of IPv6 addresses or networks. Addresses must be in IP/mask format and must not include zone_id notation as described in [RFC 4007](https://www.rfc-editor.org/rfc/rfc4007). Must not be an empty list. + + If "::/0" is included in this list, all IPv6 addresses are affected by this rule. + example: + - 2001:DB8::/128 + items: + type: string + label: + type: string + description: | + Used to identify this rule. For display purposes + only. + example: firewallrule123 + minLength: 3 + maxLength: 32 + ports: + type: string + description: |- + A string representing the port or ports affected by this rule: + + - The string may be a single port, a range of ports, or a comma-separated list of single ports and port ranges. A space is permitted following each comma. + - A range of ports is inclusive of the start and end values for the range. The end value of the range must be greater than the start value. + - Ports must be within 1 and 65535, and may not contain any leading zeroes. For example, port "080" is not allowed. + - The ports string can have up to 15 _pieces_, where a single port is treated as one piece, and a port range is treated as two pieces. For example, the string "22-24, 80, 443" has four pieces. + - If no ports are configured, all ports are affected. + - Only allowed for the TCP and UDP protocols. Ports are not allowed for the ICMP and IPENCAP protocols. + example: 22-24, 80, 443 + nullable: true + protocol: + type: string + description: | + The type of network traffic affected by this rule. + example: TCP + enum: + - TCP + - UDP + - ICMP + - IPENCAP + x-linode-cli-format: json + inbound_policy: + type: string + description: | + The default behavior for inbound traffic. This setting can be + overridden by [updating](https://techdocs.akamai.com/linode-api/reference/put-firewall-rules) + the `inbound.action` property of the Firewall Rule. + example: DROP + enum: + - ACCEPT + - DROP + outbound: + type: array + description: | + The outbound rules for the firewall, as a JSON array. + items: + type: object + description: | + One of a Firewall's inbound or outbound access rules. + The `ports` property can be used to allow traffic + on a comma-separated list of different ports. + x-akamai: + file-path: schemas/firewall-rule-config.yaml + additionalProperties: false + properties: + description: + type: string + description: | + Used to describe this rule. For display purposes + only. + example: An example firewall rule description. + minLength: 1 + maxLength: 100 + action: + type: string + description: | + Controls whether traffic is accepted or dropped by + this rule. Overrides the Firewall's `inbound_policy` + if this is an inbound rule, or the `outbound_policy` + if this is an outbound rule. + example: ACCEPT + enum: + - ACCEPT + - DROP + addresses: + type: object + description: |- + The IPv4 and/or IPv6 addresses affected by this rule. A Rule can have up to 255 total addresses or networks listed across its IPv4 and IPv6 arrays. A network and a single IP are treated as equivalent when accounting for this limit. + + Must contain `ipv4`, `ipv6`, or both. + additionalProperties: false + properties: + ipv4: + type: array + description: |- + A list of IPv4 addresses or networks. Addresses must be in IP/mask format. Must not be an empty list. + + If "0.0.0.0/0" is included in this list, all IPv4 addresses are affected by this rule. + example: + - 192.0.2.0/24 + - 198.51.100.2/32 + items: + type: string + ipv6: + type: array + description: |- + A list of IPv6 addresses or networks. Addresses must be in IP/mask format and must not include zone_id notation as described in [RFC 4007](https://www.rfc-editor.org/rfc/rfc4007). Must not be an empty list. + + If "::/0" is included in this list, all IPv6 addresses are affected by this rule. + example: + - 2001:DB8::/128 + items: + type: string + label: + type: string + description: | + Used to identify this rule. For display purposes + only. + example: firewallrule123 + minLength: 3 + maxLength: 32 + ports: + type: string + description: |- + A string representing the port or ports affected by this rule: + + - The string may be a single port, a range of ports, or a comma-separated list of single ports and port ranges. A space is permitted following each comma. + - A range of ports is inclusive of the start and end values for the range. The end value of the range must be greater than the start value. + - Ports must be within 1 and 65535, and may not contain any leading zeroes. For example, port "080" is not allowed. + - The ports string can have up to 15 _pieces_, where a single port is treated as one piece, and a port range is treated as two pieces. For example, the string "22-24, 80, 443" has four pieces. + - If no ports are configured, all ports are affected. + - Only allowed for the TCP and UDP protocols. Ports are not allowed for the ICMP and IPENCAP protocols. + example: 22-24, 80, 443 + nullable: true + protocol: + type: string + description: | + The type of network traffic affected by this rule. + example: TCP + enum: + - TCP + - UDP + - ICMP + - IPENCAP + x-linode-cli-format: json + outbound_policy: + type: string + description: | + The default behavior for outbound traffic. This setting can + be overridden by [updating](https://techdocs.akamai.com/linode-api/reference/put-firewall-rules) + the `outbound.action` property of the Firewall Rule. + example: DROP + enum: + - ACCEPT + - DROP + status: + type: string + description: |- + __Read-only__ The status of this Firewall. + + - When a Firewall is first created its status is `enabled`. + - RUn the [Update a firewall](https://techdocs.akamai.com/linode-api/reference/put-firewall) operation to set a Firewall's status to `enabled` or `disabled`. + - RUn the [Delete a firewall](https://techdocs.akamai.com/linode-api/reference/delete-firewall) operation to delete a Firewall. + example: enabled + readOnly: true + enum: + - enabled + - disabled + - deleted + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Firewall was last updated. + example: '2018-01-02T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 5 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-node-balancer-firewalls security: - personalAccessToken: [] - oauth: - - account:read_only + - nodebalancers:read_only + 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 + x-linode-cli-action: firewalls + x-linode-grant: read_only + x-original-op-id: getNodeBalancerFirewalls + x-original-op-title: Firewalls List + x-linode-cli-command: nodebalancers + /nodebalancers/{nodeBalancerId}/stats: + x-akamai: + file-path: paths/stats.yaml + path-info: /nodebalancers/{nodeBalancerId}/stats + parameters: + - name: nodeBalancerId + in: path + description: | + The ID of the NodeBalancer to access. + example: '{{nodeBalancerId}}' + x-akamai: + file-path: parameters/node-balancer-id.yaml + required: true + schema: + type: integer + get: + operationId: get-node-balancer-stats + summary: Get node balancer statistics + tags: + - Statistics + description: |- + Returns detailed statistics about the requested NodeBalancer. + + + --- + + + - __CLI__. + + ``` + linode-cli nodebalancers stats + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + nodebalancers:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli nodebalancers stats + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: nodebalancers:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a paginated list of Notification objects. + default: + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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. + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested stats. content: application/json: schema: type: object + description: | + Stats for this NodeBalancer. + x-akamai: + file-path: schemas/node-balancer-stats.yaml + additionalProperties: false properties: + title: + type: string + description: | + The title for the statistics generated in this response. + example: linode.com - balancer12345 (12345) - day (5 min avg) 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 + type: object + description: | + The data returned about this NodeBalancers. + additionalProperties: false + properties: + connections: + type: array + description: | + An array of key/value pairs representing unix timestamp and reading for connections + to this NodeBalancer. + items: + type: number + example: + - 1526391300000 + - 0 + traffic: + type: object + description: | + Traffic statistics for this NodeBalancer. + additionalProperties: false + properties: + in: + type: array + description: | + An array of key/value pairs representing unix timestamp and reading + for inbound traffic. + items: + type: number + example: + - 1526391300000 + - 631.21 + out: + type: array + description: | + An array of key/value pairs representing unix timestamp and reading + for outbound traffic. + items: + type: number + example: + - 1526391300000 + - 103.44 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-node-balancer-stats security: - personalAccessToken: [] - oauth: - - account:read_write + - nodebalancers:read_only + x-linode-cli-action: stats + x-linode-cli-skip: true + x-linode-grant: read_only + x-original-op-id: get-node-balancer-stats + x-original-op-title: NodeBalancer Statistics + View + x-linode-cli-command: nodebalancers + /object-storage/buckets: + x-akamai: + file-path: paths/buckets.yaml + path-info: /object-storage/buckets + post: + servers: + - url: https://api.linode.com/v4 + operationId: post-object-storage-bucket + summary: Create an object storage bucket + tags: + - Buckets + description: |- + Creates an Object Storage Bucket in the specified cluster. + + Accounts with negative balances cannot access this operation. + + If the bucket already exists and is owned by you, this operation returns a `200` response with that bucket as if it had just been created. + + This operation 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. + + + --- + + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the OAuth Client to create. + description: | + Information about the bucket you want to create. content: application/json: schema: - allOf: - - $ref: '#/components/schemas/OAuthClient' + type: object + additionalProperties: false required: - label - - redirect_uri + - cluster + properties: + acl: + type: string + 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. + example: '{{acl}}' + default: private + enum: + - private + - public-read + - authenticated-read + - public-read-write + cluster: + type: string + description: | + The ID of the Object Storage Cluster where this bucket should be created. + example: '{{cluster}}' + 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: '{{cors_enabled}}' + default: false + 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. + example: '{{label}}' + pattern: ^[a-z0-09][a-z0-9-]*[a-z0-9]?$ + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Client created successfully. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The bucket created successfully. 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 + type: object + description: | + An Object Storage Bucket. This should be accessed primarily through the S3 API; [click here + for more information](https://docs.ceph.com/en/latest/radosgw/s3/#api). + x-akamai: + file-path: schemas/object-storage-bucket.yaml + additionalProperties: false + properties: + cluster: + type: string + description: | + The ID of the Object Storage Cluster this bucket is in. + example: us-east-1 + created: + type: string + description: | + When this bucket was created. + example: '2019-01-01T01:23:45' + format: date-time + hostname: + type: string + description: | + The hostname where this bucket can be accessed. This hostname can be accessed through + a browser if the bucket is made public. + example: example-bucket.us-east-1.linodeobjects.com + label: + type: string + description: | + The name of this bucket. + example: example-bucket + objects: + type: integer + description: | + The number of objects stored in this bucket. + example: 4 + size: + type: integer + description: | + The size of the bucket in bytes. + example: 188318981 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket 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' + - object_storage:read_write 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: + - 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/ + x-linode-cli-skip: true + x-original-op-id: createObjectStorageBucket + x-original-op-title: Object Storage Bucket Create + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-object-storage-buckets + summary: List object storage buckets 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 + - Buckets + description: |- + Returns a paginated list of all Object Storage Buckets that you own. + + This operation 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. + + + --- + + + - __OAuth__. + + ``` + object_storage:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Client deleted successfully. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of buckets you own. content: application/json: schema: - $ref: '#/components/schemas/OAuthClient' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An Object Storage Bucket. This should be accessed primarily through the S3 API; + [click here for more information](https://docs.ceph.com/en/latest/radosgw/s3/#api). + x-akamai: + file-path: schemas/object-storage-bucket.yaml + additionalProperties: false + properties: + cluster: + type: string + description: | + The ID of the Object Storage Cluster this bucket is in. + example: us-east-1 + created: + type: string + description: | + When this bucket was created. + example: '2019-01-01T01:23:45' + format: date-time + hostname: + type: string + description: | + The hostname where this bucket can be accessed. This hostname can be + accessed through a browser if the bucket is made public. + example: example-bucket.us-east-1.linodeobjects.com + label: + type: string + description: | + The name of this bucket. + example: example-bucket + objects: + type: integer + description: | + The number of objects stored in this bucket. + example: 4 + size: + type: integer + description: | + The size of the bucket in bytes. + example: 188318981 + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only 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 + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/object-storage/buckets/ + x-linode-cli-skip: true + x-original-op-id: getObjectStorageBuckets + x-original-op-title: Object Storage Buckets List + /object-storage/buckets/{clusterId}: + x-akamai: + file-path: paths/buckets-cluster.yaml + path-info: /object-storage/buckets/{clusterId} parameters: - - name: clientId - in: path - description: The OAuth Client ID to look up. - required: true - schema: - type: string + - name: clusterId + in: path + description: | + ID of the Kubernetes cluster to look up. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path.yaml + required: true + schema: + type: integer get: + servers: + - url: https://api.linode.com/v4 + operationId: get-object-storage-bucketin-cluster + summary: List object storage buckets in cluster 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 + - Buckets + description: |- + Returns a list of Buckets in this cluster belonging to this Account. + + This operation 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. + + + --- + + + - __OAuth__. + + ``` + object_storage:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: The image to set as the thumbnail. - required: true content: - image/png: - schema: - type: string - format: binary + application/json: {} responses: - '200': - description: Thumbnail updated successfully. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of buckets you own in this cluster. content: application/json: schema: type: object + additionalProperties: false properties: data: type: array items: - $ref: '#/components/schemas/PaymentMethod' + type: object + description: | + An Object Storage Bucket. This should be accessed primarily through the S3 API; + [click here for more information](https://docs.ceph.com/en/latest/radosgw/s3/#api). + x-akamai: + file-path: schemas/object-storage-bucket.yaml + additionalProperties: false + properties: + cluster: + type: string + description: | + The ID of the Object Storage Cluster this bucket is in. + example: us-east-1 + created: + type: string + description: | + When this bucket was created. + example: '2019-01-01T01:23:45' + format: date-time + hostname: + type: string + description: | + The hostname where this bucket can be accessed. This hostname can be + accessed through a browser if the bucket is made public. + example: example-bucket.us-east-1.linodeobjects.com + label: + type: string + description: | + The name of this bucket. + example: example-bucket + objects: + type: integer + description: | + The number of objects stored in this bucket. + example: 4 + size: + type: integer + description: | + The size of the bucket in bytes. + example: 188318981 page: - $ref: '#/components/schemas/PaginationEnvelope/properties/page' + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true pages: - $ref: '#/components/schemas/PaginationEnvelope/properties/pages' + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true results: - $ref: '#/components/schemas/PaginationEnvelope/properties/results' - default: - $ref: '#/components/responses/ErrorResponse' + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucketin-cluster + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only 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: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/object-storage/buckets/us-east-1 + x-linode-cli-skip: true + x-original-op-id: getObjectStorageBucketinCluster + x-original-op-title: Object Storage Buckets in + Cluster List + /object-storage/buckets/{clusterId}/{bucket}: + x-akamai: + file-path: paths/bucket.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket} + parameters: + - name: clusterId + in: path + description: | + ID of the Kubernetes cluster to look up. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path.yaml + required: true + schema: + type: integer + - name: bucket + in: path + description: | + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string + get: servers: - - url: https://api.linode.com/v4 - x-linode-grant: read_write + - url: https://api.linode.com/v4 + operationId: get-object-storage-bucket + summary: Get an object storage bucket tags: - - Account - summary: Payment Method Add - description: | - Adds a Payment Method to your Account with the option to set it as the default method. + - Buckets + description: |- + Returns a single Object Storage Bucket. - * Adding a default Payment Method removes the default status from any other Payment Method. + This operation 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. - * 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. + - __OAuth__. - **Parent and child accounts** + ``` + object_storage:read_only + ``` - 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] 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' + application/json: {} responses: - '200': - description: Payment Method added. + default: + description: | + Error content: application/json: schema: type: object - default: - $ref: '#/components/responses/ErrorResponse' - x-code-samples: - - lang: Shell - source: > - curl -H "Content-Type: application/json" \ - -H "Authorization: Bearer $TOKEN" \ - -X POST -d '{ - "type": "credit_card", - "is_default": true, - "data": { - "card_number": "4111111111111111", - "expiry_month": 11, - "expiry_year": 2020, - "cvv": "111" - } - }' \ - https://api.linode.com/v4/account/payment-methods - - lang: CLI - source: > - linode-cli payment-methods add \ - --type credit_card \ - --is_default true \ - --data.card_number 4111111111111111 \ - --data.expiry_month 11 \ - --data.expiry_year 2020 \ - --data.cvv 111 - /account/payment-methods/{paymentMethodId}: - x-linode-cli-command: payment-methods - parameters: - - name: paymentMethodId - in: path - description: The ID of the Payment Method to look up. - required: true - schema: - type: integer - get: - servers: - - url: https://api.linode.com/v4 - x-linode-grant: read_only - tags: - - Account - summary: Payment Method View - description: | - View the details of the specified Payment Method. - operationId: getPaymentMethod - x-linode-cli-action: view - security: - - personalAccessToken: [] - - oauth: - - account:read_only - responses: - '200': - description: Returns a Payment Method Object. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested bucket. content: application/json: schema: - $ref: '#/components/schemas/PaymentMethod' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + description: | + An Object Storage Bucket. This should be accessed primarily through the S3 API; [click here + for more information](https://docs.ceph.com/en/latest/radosgw/s3/#api). + x-akamai: + file-path: schemas/object-storage-bucket.yaml + additionalProperties: false + properties: + cluster: + type: string + description: | + The ID of the Object Storage Cluster this bucket is in. + example: us-east-1 + created: + type: string + description: | + When this bucket was created. + example: '2019-01-01T01:23:45' + format: date-time + hostname: + type: string + description: | + The hostname where this bucket can be accessed. This hostname can be accessed through + a browser if the bucket is made public. + example: example-bucket.us-east-1.linodeobjects.com + label: + type: string + description: | + The name of this bucket. + example: example-bucket + objects: + type: integer + description: | + The number of objects stored in this bucket. + example: 4 + size: + type: integer + description: | + The size of the bucket in bytes. + example: 188318981 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucket + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only 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 + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket + x-linode-cli-skip: true + x-original-op-id: getObjectStorageBucket + x-original-op-title: Object Storage Bucket View delete: - x-linode-grant: read_write + servers: + - url: https://api.linode.com/v4 + operationId: delete-object-storage-bucket + summary: Remove an object storage bucket tags: - - Account - summary: Payment Method Delete - description: | - Deactivate the specified Payment Method. + - Buckets + description: |- + Removes a single bucket. - 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 + Bucket objects must be removed prior to removing the bucket. While buckets containing objects _may_ be deleted using the [s3cmd command-line tool](https://www.linode.com/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 operation 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. + + + --- + + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Payment Method deactivated. + default: + description: | + Error content: application/json: schema: type: object - default: - $ref: '#/components/responses/ErrorResponse' + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Bucket deleted successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-object-storage-bucket + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write 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 + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + -X DELETE \ + https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket + x-linode-cli-skip: true + x-original-op-id: deleteObjectStorageBucket + x-original-op-title: Object Storage Bucket Remove + /object-storage/buckets/{clusterId}/{bucket}/access: + x-akamai: + file-path: paths/access.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket}/access parameters: - - name: paymentMethodId + - name: clusterId in: path - description: The ID of the Payment Method to make default. + description: | + The ID of the cluster this bucket exists in. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id.yaml required: true schema: - type: integer + type: string + - name: bucket + in: path + description: | + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string post: servers: - - url: https://api.linode.com/v4 - x-linode-grant: read_write + - url: https://api.linode.com/v4 + operationId: post-object-storage-bucket-access + summary: Modify access to an object storage bucket 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. + - Bucket access + 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. - **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 + --- + + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The changes to make to the bucket's access controls. + content: + application/json: + schema: + additionalProperties: false + properties: + acl: + type: string + 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 + enum: + - private + - public-read + - authenticated-read + - public-read-write + - custom + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json 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. + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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' + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Access controls updated. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket-access + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write 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 + - 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 + x-linode-cli-skip: true + x-original-op-id: modifyObjectStorageBucketAccess + x-original-op-title: Object Storage Bucket Access + Modify + put: + servers: + - url: https://api.linode.com/v4 + operationId: put-storage-bucket-access + summary: Update access to an object storage bucket tags: - - Account - summary: Payment Make - description: | - Makes a Payment to your Account. + - Bucket access + 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. - * The requested amount is charged to the default Payment Method if no `payment_method_id` is specified. + 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. - * 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 + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the Payment you are making. - required: true + description: | + The changes to make to the bucket's access controls. content: application/json: schema: + additionalProperties: false properties: - usd: + acl: 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 + 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 + enum: + - private + - public-read + - authenticated-read + - public-read-write + - custom + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Payment submitted successfully. + default: + description: | + Error 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. - 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Access controls updated. 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 + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-storage-bucket-access 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' + - object_storage:read_write 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 + - 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 x-linode-cli-skip: true - tags: - - Account - summary: Staged/Approved PayPal Payment Execute + x-original-op-id: updateObjectStorageBucketAccess + x-original-op-title: Object Storage Bucket Access + Update + /object-storage/buckets/{clusterId}/{bucket}/object-acl: + x-akamai: + file-path: paths/object-acl.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket}/object-acl + parameters: + - name: clusterId + in: path 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 + The ID of the cluster this bucket exists in. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path-7b27f6d9.yaml + required: true + schema: + type: string + - name: bucket + in: path description: | - Adds an expiring Promo Credit to your account. The following restrictions apply: + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-object-storage-bucket-acl + summary: Get an object storage object ACL config + tags: + - ACL configurations + 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. - * Your account needs to be less than 90 days old. + This operation 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. - * 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** + - __OAuth__. - In a [parent and child account](/docs/guides/parent-child-accounts/) environment, the following apply: + ``` + object_storage:read_only + ``` - * 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: name + in: query + description: | + The `name` of the object for which to retrieve its Access Control List (ACL). Run the [List object storage + bucket contents](https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucket-content) + operation to access all object names in a bucket. + example: '{{name}}' + x-akamai: + file-path: parameters/name-query.yaml + required: true + schema: + type: string 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. + application/json: {} 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. + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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' + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The Object's canned ACL and policy. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + acl: + type: string + 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 + enum: + - private + - public-read + - authenticated-read + - public-read-write + - custom + acl_xml: + type: string + description: | + The full XML of the object's ACL policy. + example: ... + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucket-acl + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only x-code-samples: - lang: Shell - source: > + 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 + https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-acl?name=example.txt + x-linode-cli-skip: true + x-original-op-id: viewObjectStorageBucketACL + x-original-op-title: Object Storage Object ACL + Config View + put: + servers: + - url: https://api.linode.com/v4 + operationId: put-object-storage-bucket-acl + summary: Update an object's ACL config 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. + - ACL configurations + 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. - 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. + This operation 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. - 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. + - __OAuth__. - * have any shared IP addresses. + ``` + object_storage:read_write + ``` - * have any assigned /56, /64, or /116 IPv6 ranges. - operationId: createServiceTransfer - x-linode-cli-action: create - security: - - personalAccessToken: [] - - oauth: - - account:read_write + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: The services to include in this transfer request. + description: | + The changes to make to this Object's access controls. content: application/json: schema: + additionalProperties: false required: - - entities - type: object + - acl + - name 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 + name: + type: string + description: | + The `name` of the object for which to update its Access Control List (ACL). Run the [List + object storage bucket contents](https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucket-content) + operation to access all object names in a bucket. + acl: + type: string + 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 + enum: + - private + - public-read + - authenticated-read + - public-read-write + - custom + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: > - Returns a Service Transfer object containing the details of the transfer for the specified token. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The Object's canned ACL and policy. content: application/json: schema: type: object - default: - $ref: '#/components/responses/ErrorResponse' + additionalProperties: false + properties: + acl: + type: string + 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 + enum: + - private + - public-read + - authenticated-read + - public-read-write + - custom + acl_xml: + type: string + description: | + The full XML of the object's ACL policy. + example: ... + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-object-storage-bucket-acl + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write 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 + 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 + x-linode-cli-skip: true + x-original-op-id: updateObjectStorageBucketACL + x-original-op-title: Object Storage Object ACL + Config Update + /object-storage/buckets/{clusterId}/{bucket}/object-list: + x-akamai: + file-path: paths/object-list.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket}/object-list 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 + - name: clusterId + in: path 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. + The ID of the cluster this bucket exists in. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path-7b27f6d9.yaml + required: true + schema: + type: string + - name: bucket + in: path + description: | + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-object-storage-bucket-content + summary: List object storage bucket contents + tags: + - Bucket contents + 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. - 1. The service must still be owned by the account that created the transfer. + This operation 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. - 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. + - __OAuth__. - * have any assigned /56, /64, or /116 IPv6 ranges. + ``` + object_storage:read_only + ``` - 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: marker + in: query + 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. + example: '{{marker}}' + x-akamai: + file-path: parameters/marker-query.yaml + required: false + schema: + type: string + - name: delimiter + in: query + 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. + example: '{{delimiter}}' + x-akamai: + file-path: parameters/delimiter-query.yaml + required: false + schema: + type: string + - name: prefix + in: query + 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. + example: '{{prefix}}' + x-akamai: + file-path: parameters/prefix-query.yaml + required: false + schema: + type: string + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} responses: - '200': - description: > - Service Transfer accepted. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + One page of the requested bucket's contents. 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 + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An Object in Object Storage, or a "prefix" that contains one or more objects when + a `delimiter` is used. + x-akamai: + file-path: schemas/object-storage-object.yaml + additionalProperties: false + properties: + name: + type: string + description: | + The name of this object or prefix. + example: example + etag: + type: string + description: | + An MD-5 hash of the object. `null` if this object represents a prefix. + example: 9f254c71e28e033bf9e0e5262e3e72ab + last_modified: + type: string + description: | + The date and time this object was last modified. `null` if this object + represents a prefix. + example: '2019-01-01T01:23:45' + format: date-time + owner: + type: string + description: | + The owner of this object, as a UUID. `null` if this object represents + a prefix. + example: bfc70ab2-e3d4-42a4-ad55-83921822270c + size: + type: integer + description: | + The size of this object, in bytes. `null` if this object represents a prefix. + example: 123 + is_truncated: + type: boolean + description: | + Designates if there is another page of bucket objects. + example: true + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-bucket-content 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' + - object_storage:read_only 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 + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/object-storage/buckets/us-east-1/example-bucket/object-list + x-linode-cli-skip: true + x-original-op-id: getObjectStorageBucketContent + x-original-op-title: Object Storage Bucket Contents + List + /object-storage/buckets/{clusterId}/{bucket}/object-url: + x-akamai: + file-path: paths/object-url.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket}/object-url + parameters: + - name: clusterId + in: path 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 + The ID of the cluster this bucket exists in. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path-7b27f6d9.yaml + required: true + schema: + type: string + - name: bucket + in: path + description: | + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string post: - x-linode-grant: unrestricted only + servers: + - url: https://api.linode.com/v4 + operationId: post-object-storage-object-url + summary: Create a URL for an object 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. + - Buckets + 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. - **Note:** This command can only be accessed by account users with *unrestricted* access. + This operation 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. - **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. + - __OAuth__. - * A child account user can create new child account users. + ``` + object_storage:read_write + ``` - * 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the User to create. + description: | + Information about the request to sign. content: application/json: schema: - allOf: - - $ref: '#/components/schemas/User' + additionalProperties: false required: - - username - - email + - name + - method + properties: + 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 + 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 + default: 3600 + minimum: 360 + maximum: 86400 + method: + type: string + description: | + The HTTP method allowed to be used with the pre-signed URL. + example: GET + default: GET + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: New User created successfully. + default: + description: | + Error 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 + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The URL with which to access your 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 + additionalProperties: false + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-object-storage-object-url + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write + 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 + x-linode-cli-skip: true + x-original-op-id: createObjectStorageObjectURL + x-original-op-title: Object Storage Object URL + Create + /object-storage/buckets/{clusterId}/{bucket}/ssl: + x-akamai: + file-path: paths/bucket-ssl.yaml + path-info: /object-storage/buckets/{clusterId}/{bucket}/ssl + parameters: + - name: clusterId + in: path + description: | + ID of the Kubernetes cluster to look up. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path.yaml + required: true + schema: + type: integer + - name: bucket + in: path 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. + The bucket name. + example: '{{bucket}}' + x-akamai: + file-path: parameters/bucket.yaml + required: true + schema: + type: string + post: + servers: + - url: https://api.linode.com/v4 + operationId: post-object-storage-ssl + summary: Upload an object storage TLS/SSL certificate + tags: + - TLS/SSL certificates + 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. - **Note:** This command can only be accessed by account users with *unrestricted* access. + To replace an expired certificate, [delete your current certificates](https://techdocs.akamai.com/linode-api/reference/delete-object-storage-ssl) and upload a new one. - **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. + - __CLI__. - * 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 + ``` + linode-cli object-storage ssl-upload + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage ssl-upload + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: The information to update. + description: | + Upload this TLS/SSL certificate with its corresponding secret key. 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: + type: object + description: | + Upload a TLS/SSL certificate and private key to be served when you visit your Object Storage bucket + via HTTPS. + x-akamai: + file-path: schemas/object-storage-ssl.yaml + additionalProperties: false + required: + - certificate + - private_key + properties: + certificate: + type: string + description: |- + Your Base64 encoded and PEM formatted SSL certificate. - * 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. + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI) + example: '{{certificate}}' + private_key: + type: string + description: |- + The private key associated with this TLS/SSL certificate. - * 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 + Line breaks must be represented as "\n" in the string for requests (but not when using the Linode CLI) + example: '{{private_key}}' + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: User deleted successfully. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 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/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' + type: object + description: | + If this Object Storage bucket has a corresponding TLS/SSL Certificate. + x-akamai: + file-path: schemas/object-storage-ssl-response.yaml + additionalProperties: false + properties: + ssl: + type: boolean + description: | + __Read-only__ A boolean indicating if this Bucket has a corresponding TLS/SSL certificate + that was uploaded by an Account user. + example: true + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-object-storage-ssl + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write 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 + - 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-----" + x-linode-cli-action: ssl-upload + x-original-op-id: createObjectStorageSSL + x-original-op-title: Object Storage TLS/SSL Cert + Upload + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-object-storage-ssl + summary: Get an object storage TLS/SSL certificate 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. + - TLS/SSL certificates + description: |- + Returns a boolean value indicating if this bucket has a corresponding TLS/SSL certificate that was uploaded by an Account user. - **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). + - __CLI__. - * An unrestricted child account user can configure all other grants for the proxy user, via `global` object. + ``` + linode-cli object-storage ssl-view + ``` - * 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 + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage ssl-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: The grants to update. Omitted grants will be left unchanged. - required: true content: - application/json: - schema: - $ref: '#/components/schemas/GrantsResponse' + application/json: {} responses: - '200': - description: Grants updated successfully. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 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: - allOf: - - $ref: '#/components/schemas/PaginationEnvelope' - - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/BetaProgram' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + description: | + If this Object Storage bucket has a corresponding TLS/SSL Certificate. + x-akamai: + file-path: schemas/object-storage-ssl-response.yaml + additionalProperties: false + properties: + ssl: + type: boolean + description: | + __Read-only__ A boolean indicating if this Bucket has a corresponding TLS/SSL certificate + that was uploaded by an Account user. + example: true + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-ssl + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only x-code-samples: - lang: Shell - source: > - curl https://api.linode.com/v4/betas \ - -H "Authorization: Bearer $TOKEN" + 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 betas list - /betas/{betaId}: - x-linode-cli-command: betas - parameters: - - $ref: '#/components/parameters/betaId' - get: - tags: - - Beta Programs - summary: Beta Program View - operationId: getBetaProgram + source: |- + linode-cli object-storage ssl-view \ + us-east-1 example-bucket + x-linode-cli-action: ssl-view + x-original-op-id: getObjectStorageSSL + x-original-op-title: Object Storage TLS/SSL Cert + View + delete: 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. + operationId: delete-object-storage-ssl + summary: Delete an object storage TLS/SSL certificate + tags: + - TLS/SSL certificates + description: |- + Deletes this Object Storage bucket's user uploaded TLS/SSL certificate and private key. + + + --- + + + - __CLI__. + + ``` + linode-cli object-storage ssl-delete + ``` - Only unrestricted Users can access this command. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage ssl-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a paginated list of all available Beta Program objects. + default: + description: | + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Deletes this Object Storage bucket's user uploaded TLS/SSL certificate and private key. 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' + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-object-storage-ssl + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write x-code-samples: - lang: Shell - source: > - curl https://api.linode.com/v4/databases/engines/ + 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 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 + source: |- + linode-cli object-storage ssl-delete \ + us-east-1 example-bucket + x-linode-cli-action: ssl-delete + x-original-op-id: deleteObjectStorageSSL + x-original-op-title: Object Storage TLS/SSL Cert + Delete + x-linode-cli-command: object-storage + /object-storage/cancel: + x-akamai: + file-path: paths/object-storage-cancel.yaml + path-info: /object-storage/cancel + post: 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.** + operationId: post-cancel-object-storage + summary: Cancel object storage + tags: + - Object storage + description: |- + Cancel Object Storage on an Account. - Display information for a single Managed Database engine type and version. + __Warning__: Removes all buckets and their contents from your Account. This data is irretrievable once removed. + + + --- + + + - __CLI__. + + ``` + linode-cli object-storage cancel + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage cancel + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns information for a single Managed Database engine type and version. + default: + description: | + Error content: application/json: schema: - $ref: '#/components/schemas/DatabaseEngine' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Object Storage cancellation successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-cancel-object-storage + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write x-code-samples: - lang: Shell - source: > - curl https://api.linode.com/v4/databases/engines/mysql/5.7.30 + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + -X POST \ + https://api.linode.com/v4/object-storage/cancel - lang: CLI - source: > - linode-cli databases engine-view mysql/5.7.30 - /databases/instances: - x-linode-cli-command: databases + source: linode-cli object-storage cancel + x-linode-cli-action: cancel + x-original-op-id: cancelObjectStorage + x-original-op-title: Object Storage Cancel + x-linode-cli-command: object-storage + /object-storage/clusters: + x-akamai: + file-path: paths/object-storage-clusters.yaml + path-info: /object-storage/clusters 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' + operationId: get-object-storage-clusters + summary: List clusters + tags: + - Clusters 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 + 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. + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a paginated list of all accessible Managed Databases on your Account. + default: + description: | + Error 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' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of available clusters. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An Object Storage Cluster + x-akamai: + file-path: schemas/object-storage-cluster.yaml + additionalProperties: false + properties: + id: + type: string + description: | + The unique ID for this cluster. + example: us-east-1 + domain: + type: string + description: | + The base URL for this cluster, used for connecting with third-party + clients. + example: us-east-1.linodeobjects.com + region: + type: string + description: | + The region where this cluster is located. + example: us-east + static_site_domain: + type: string + description: | + The base URL for this cluster used when hosting static sites. + example: website-us-east-1.linodeobjects.com + status: + type: string + description: | + This cluster's status. + example: available + enum: + - available + - unavailable + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-clusters x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/instances + https://api.linode.com/v4/object-storage/clusters - lang: CLI - source: > - linode-cli databases list - /databases/mysql/instances: - x-linode-cli-command: databases + source: linode-cli object-storage clusters-list + x-linode-cli-action: clusters-list + x-original-op-id: getObjectStorageClusters + x-original-op-title: Clusters List + x-linode-cli-command: object-storage + /object-storage/clusters/{clusterId}: + x-akamai: + file-path: paths/object-storage-cluster.yaml + path-info: /object-storage/clusters/{clusterId} + parameters: + - name: clusterId + in: path + description: | + The ID of the Cluster. + example: '{{clusterId}}' + x-akamai: + file-path: parameters/cluster-id-path-f8f10b45.yaml + required: true + schema: + type: string 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' + operationId: get-object-storage-cluster + summary: Get a cluster + tags: + - Clusters 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 + Returns a single Object Storage Cluster. + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a paginated list of all accessible Managed MySQL Databases on your Account. + default: + description: | + Error 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' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested Cluster + content: + application/json: + schema: + type: object + description: | + An Object Storage Cluster + x-akamai: + file-path: schemas/object-storage-cluster.yaml + additionalProperties: false + properties: + id: + type: string + description: | + The unique ID for this cluster. + example: us-east-1 + domain: + type: string + description: | + The base URL for this cluster, used for connecting with third-party clients. + example: us-east-1.linodeobjects.com + region: + type: string + description: | + The region where this cluster is located. + example: us-east + static_site_domain: + type: string + description: | + The base URL for this cluster used when hosting static sites. + example: website-us-east-1.linodeobjects.com + status: + type: string + description: | + This cluster's status. + example: available + enum: + - available + - unavailable + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-cluster x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/mysql/instances/ + https://api.linode.com/v4/object-storage/clusters/us-east-1 - lang: CLI - source: > - linode-cli databases mysql-list + source: linode-cli object-storage clusters-view us-east-1 + x-linode-cli-action: clusters-view + x-original-op-id: getObjectStorageCluster + x-original-op-title: Cluster View + x-linode-cli-command: object-storage + /object-storage/keys: + x-akamai: + file-path: paths/keys.yaml + path-info: /object-storage/keys 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. + operationId: post-object-storage-keys + summary: Create an object storage key + tags: + - Keys + description: |- + Provisions a new Object Storage Key on your account. - New instances can take approximately 15 to 30 minutes to provision. + - Accounts with negative balances cannot access this operation. + - 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. - 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. + - __CLI__. - 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. + ``` + linode-cli object-storage keys-create + ``` - 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. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - * 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. + - __OAuth__. - * **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. + ``` + object_storage:read_write + ``` - * 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage keys-create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the Managed MySQL Database you are creating. - x-linode-cli-allowed-defaults: - - engine - - region - - type - required: true + description: | + The label of the key to create. This is used to identify the created key. 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.** + type: object + description: | + A keypair used to communicate with the Object Storage S3 API. + x-akamai: + file-path: schemas/object-storage-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This keypair's unique ID + example: '{{id}}' + readOnly: true + access_key: + type: string + description: | + __Read-only__ This keypair's access key. This is not secret. + example: '{{access_key}}' + readOnly: true + bucket_access: + type: array + description: |- + Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions. - 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.** + Limited Access Keys can: - Remove a Managed MySQL Database from your Account. + - [list all buckets](https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket. - Requires `read_write` access to the Database. + - [create new buckets](https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket), but do not have any access to the buckets it creates, unless explicitly given access to them. - The Database must have an `active`, `failed`, or `degraded` status to perform this command. + __Note:__ You can create an Object Storage Limited Access Key without access to any buckets. + This is achieved by sending a request with an empty `bucket_access` array. - Only unrestricted Users can access this command, and have access regardless of the acting token's OAuth scopes. - security: - - personalAccessToken: [] - - oauth: - - databases:read_write + __Note:__ If this field is omitted, a regular unlimited access key is issued. + items: + type: object + additionalProperties: false + properties: + bucket_name: + type: string + description: | + The unique label of the bucket to which the key will grant limited access. + example: example-bucket + cluster: + type: string + description: | + The Object Storage cluster where a bucket to which the key is granting access + is hosted. + example: ap-south-1 + permissions: + type: string + description: | + This Limited Access Key's permissions for the selected bucket. + example: read_only + enum: + - read_write + - read_only + label: + type: string + description: | + The label given to this key. For display purposes only. + example: '{{label}}' + limited: + type: boolean + description: | + __Read-only__ Whether or not this key is a limited access key. Will return `false` if + this key grants full access to all buckets on the user's account. + example: '{{limited}}' + readOnly: true + secret_key: + type: string + description: | + __Read-only__ This keypair's secret key. Only returned on key creation. + example: '{{secret_key}}' + readOnly: true + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Managed MySQL Database successfully deleted. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The new keypair. __This is the only time__ the secret key is returned. + content: + application/json: + schema: + type: object + description: | + A keypair used to communicate with the Object Storage S3 API. + x-akamai: + file-path: schemas/object-storage-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This keypair's unique ID + example: 123 + readOnly: true + access_key: + type: string + description: | + __Read-only__ This keypair's access key. This is not secret. + example: KVAKUTGBA4WTR2NSJQ81 + readOnly: true + bucket_access: + type: array + description: |- + Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions. - * Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database. + Limited Access Keys can: - * **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. + - [list all buckets](https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket. - 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. + - [create new buckets](https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket), but do not have any access to the buckets it creates, unless explicitly given access to them. - * 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. + __Note:__ You can create an Object Storage Limited Access Key without access to any buckets. + This is achieved by sending a request with an empty `bucket_access` array. - * **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. + __Note:__ If this field is omitted, a regular unlimited access key is issued. + items: + type: object + additionalProperties: false + properties: + bucket_name: + type: string + description: | + The unique label of the bucket to which the key will grant limited access. + example: example-bucket + cluster: + type: string + description: | + The Object Storage cluster where a bucket to which the key is granting access + is hosted. + example: ap-south-1 + permissions: + type: string + description: | + This Limited Access Key's permissions for the selected bucket. + example: read_only + enum: + - read_write + - read_only + label: + type: string + description: | + The label given to this key. For display purposes only. + example: my-key + limited: + type: boolean + description: | + __Read-only__ Whether or not this key is a limited access key. Will return `false` + if this key grants full access to all buckets on the user's + account. + example: true + readOnly: true + secret_key: + type: string + description: | + __Read-only__ This keypair's secret key. Only returned on key creation. + example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-object-storage-keys 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' + - object_storage:read_write x-code-samples: - lang: Shell - source: > + 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 + -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/databases/mysql/instances/123 + https://api.linode.com/v4/object-storage/keys - 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 + 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" }]' + x-linode-cli-action: keys-create + x-original-op-id: createObjectStorageKeys + x-original-op-title: Object Storage Key Create 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.** + operationId: get-object-storage-keys + summary: List object storage keys + tags: + - Keys + description: |- + Returns a paginated list of Object Storage Keys for authenticating to the Object Storage S3 API. - 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 + - __CLI__. + + ``` + linode-cli object-storage keys-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage keys-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a paginated list of backups for the Managed MySQL Database. + default: + description: | + Error 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' + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of Object Storage Keys + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A keypair used to communicate with the Object Storage S3 API. + x-akamai: + file-path: schemas/object-storage-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This keypair's unique ID + example: 123 + readOnly: true + access_key: + type: string + description: | + __Read-only__ This keypair's access key. This is not secret. + example: KVAKUTGBA4WTR2NSJQ81 + readOnly: true + bucket_access: + type: array + description: |- + Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions. + + Limited Access Keys can: + + - [list all buckets](https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket. + + - [create new buckets](https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket), but do not have any access to the buckets it creates, unless explicitly given access to them. + + __Note:__ You can create an Object Storage Limited Access Key without access to any buckets. + This is achieved by sending a request with an empty `bucket_access` array. + + __Note:__ If this field is omitted, a regular unlimited access key is issued. + items: + type: object + additionalProperties: false + properties: + bucket_name: + type: string + description: | + The unique label of the bucket to which the key will grant + limited access. + example: example-bucket + cluster: + type: string + description: | + The Object Storage cluster where a bucket to which the key + is granting access is hosted. + example: ap-south-1 + permissions: + type: string + description: | + This Limited Access Key's permissions for the selected bucket. + example: read_only + enum: + - read_write + - read_only + label: + type: string + description: | + The label given to this key. For display purposes only. + example: my-key + limited: + type: boolean + description: | + __Read-only__ Whether or not this key is a limited access key. Will + return `false` if this key grants full access to all buckets + on the user's account. + example: true + readOnly: true + secret_key: + type: string + description: | + __Read-only__ This keypair's secret key. Only returned on key creation. + example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw + readOnly: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-keys + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/mysql/instances/123/backups + https://api.linode.com/v4/object-storage/keys - lang: CLI - source: > - linode-cli databases mysql-backups-list 123 - post: - tags: - - Databases - summary: Managed MySQL Database Backup Snapshot Create - operationId: postDatabasesMySQLInstanceBackup + source: linode-cli object-storage keys-list + x-linode-cli-action: keys-list + x-original-op-id: getObjectStorageKeys + x-original-op-title: Object Storage Keys List + x-linode-cli-command: object-storage + /object-storage/keys/{keyId}: + x-akamai: + file-path: paths/key.yaml + path-info: /object-storage/keys/{keyId} + parameters: + - name: keyId + in: path + description: | + The key to look up. + example: '{{keyId}}' + x-akamai: + file-path: parameters/key-id-path.yaml + required: true + schema: + type: integer + get: 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.** + operationId: get-object-storage-key + summary: Get an object storage key + tags: + - Keys + description: |- + Returns a single Object Storage Key provisioned for your account. - 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. + - __CLI__. - 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 + ``` + linode-cli object-storage keys-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage keys-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the snapshot backup to create. content: - application/json: - schema: - $ref: '#/components/schemas/DatabaseBackupSnapshot' + application/json: {} responses: - '200': - description: Database snapshot backup request successful. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The keypair 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.** + type: object + description: | + A keypair used to communicate with the Object Storage S3 API. + x-akamai: + file-path: schemas/object-storage-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This keypair's unique ID + example: 123 + readOnly: true + access_key: + type: string + description: | + __Read-only__ This keypair's access key. This is not secret. + example: KVAKUTGBA4WTR2NSJQ81 + readOnly: true + bucket_access: + type: array + description: |- + Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions. - Delete a single backup for an accessible Managed MySQL Database. + Limited Access Keys can: - Requires `read_write` access to the Database. + - [list all buckets](https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket. + + - [create new buckets](https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket), but do not have any access to the buckets it creates, unless explicitly given access to them. - The Database must not be provisioning to perform this command. + __Note:__ You can create an Object Storage Limited Access Key without access to any buckets. + This is achieved by sending a request with an empty `bucket_access` array. + + __Note:__ If this field is omitted, a regular unlimited access key is issued. + items: + type: object + additionalProperties: false + properties: + bucket_name: + type: string + description: | + The unique label of the bucket to which the key will grant limited access. + example: example-bucket + cluster: + type: string + description: | + The Object Storage cluster where a bucket to which the key is granting access + is hosted. + example: ap-south-1 + permissions: + type: string + description: | + This Limited Access Key's permissions for the selected bucket. + example: read_only + enum: + - read_write + - read_only + label: + type: string + description: | + The label given to this key. For display purposes only. + example: my-key + limited: + type: boolean + description: | + __Read-only__ Whether or not this key is a limited access key. Will return `false` + if this key grants full access to all buckets on the user's + account. + example: true + readOnly: true + secret_key: + type: string + description: | + __Read-only__ This keypair's secret key. Only returned on key creation. + example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-key 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' + - object_storage:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - -X DELETE \ - https://api.linode.com/v4/databases/mysql/instances/123/backups/456 + https://api.linode.com/v4/object-storage/keys/12345 - 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 + source: |- + linode-cli object-storage keys-view \ + --keyId 12345 + x-linode-cli-action: keys-view + x-original-op-id: getObjectStorageKey + x-original-op-title: Object Storage Key View + put: 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.** + operationId: put-object-storage-key + summary: Update an object storage key + tags: + - Keys + description: |- + Updates an Object Storage Key on your account. - Restore a backup to a Managed MySQL Database on your Account. + - A successful request triggers an `obj_access_key_update` event. - 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 + - __CLI__. + + ``` + linode-cli object-storage keys-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage keys-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The fields to update. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + label: + type: string + description: | + The label for this keypair, for display purposes only. + example: '{{label}}' + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Request to restore backup successful. + default: + description: | + Error 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.** + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Update Successful + content: + application/json: + schema: + type: object + description: | + A keypair used to communicate with the Object Storage S3 API. + x-akamai: + file-path: schemas/object-storage-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This keypair's unique ID + example: 123 + readOnly: true + access_key: + type: string + description: | + __Read-only__ This keypair's access key. This is not secret. + example: KVAKUTGBA4WTR2NSJQ81 + readOnly: true + bucket_access: + type: array + description: |- + Defines this key as a Limited Access Key. Limited Access Keys restrict this Object Storage key's access to only the bucket(s) declared in this array and define their bucket-level permissions. - Display the root username and password for an accessible Managed MySQL Database. + Limited Access Keys can: + + - [list all buckets](https://techdocs.akamai.com/linode-api/reference/get-object-storage-buckets) available on this Account, but cannot perform any actions on a bucket unless it has access to the bucket. + + - [create new buckets](https://techdocs.akamai.com/linode-api/reference/post-object-storage-bucket), but do not have any access to the buckets it creates, unless explicitly given access to them. + + __Note:__ You can create an Object Storage Limited Access Key without access to any buckets. + This is achieved by sending a request with an empty `bucket_access` array. - The Database must have an `active` status to perform this command. + __Note:__ If this field is omitted, a regular unlimited access key is issued. + items: + type: object + additionalProperties: false + properties: + bucket_name: + type: string + description: | + The unique label of the bucket to which the key will grant limited access. + example: example-bucket + cluster: + type: string + description: | + The Object Storage cluster where a bucket to which the key is granting access + is hosted. + example: ap-south-1 + permissions: + type: string + description: | + This Limited Access Key's permissions for the selected bucket. + example: read_only + enum: + - read_write + - read_only + label: + type: string + description: | + The label given to this key. For display purposes only. + example: my-key + limited: + type: boolean + description: | + __Read-only__ Whether or not this key is a limited access key. Will return `false` + if this key grants full access to all buckets on the user's + account. + example: true + readOnly: true + secret_key: + type: string + description: | + __Read-only__ This keypair's secret key. Only returned on key creation. + example: OiA6F5r0niLs3QA2stbyq7mY5VCV7KqOzcmitmHw + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-object-storage-key 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' + - object_storage:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/mysql/instances/123/credentials/ + 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 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 + source: |- + linode-cli object-storage keys-update \ + --keyId 12345 + --label "my-object-storage-key" + x-linode-cli-action: keys-update + x-original-op-id: updateObjectStorageKey + x-original-op-title: Object Storage Key Update + delete: 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.** + operationId: delete-object-storage-key + summary: Revoke an object storage key + tags: + - Keys + description: |- + Revokes an Object Storage Key. This keypair will no longer be usable by third-party clients. - Reset the root password for a Managed MySQL Database. + - A successful request triggers an `obj_access_key_delete` event. - 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 + - __CLI__. + + ``` + linode-cli object-storage keys-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + object_storage:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli object-storage keys-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: object_storage:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Managed Database instance credentials successfully reset. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Deletion successful content: application/json: schema: - $ref: '#/components/schemas/DatabaseSSL' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-object-storage-key + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_write x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/mysql/instances/123/ssl + -X DELETE \ + https://api.linode.com/v4/object-storage/keys/12345 - 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 + source: linode-cli object-storage keys-delete 12345 + x-linode-cli-action: keys-delete + x-original-op-id: deleteObjectStorageKey + x-original-op-title: Object Storage Key Revoke + x-linode-cli-command: object-storage + /object-storage/transfer: + x-akamai: + file-path: paths/object-storage-transfer.yaml + path-info: /object-storage/transfer + get: 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.** + operationId: get-object-storage-transfer + summary: Get object storage transfer data + tags: + - Object storage + 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](https://www.linode.com/docs/products/storage/object-storage/#pricing) guide for details on Object Storage transfer quotas. - 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** + - __OAuth__. - * 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. + ``` + object_storage:read_only + ``` - * **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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: object_storage:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Managed Database instance patch request successful. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns the amount of outbound data transfer used by your account's Object Storage buckets. 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' + additionalProperties: false + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-object-storage-transfer + security: + - personalAccessToken: [] + - oauth: + - object_storage:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/ - - lang: CLI - source: > - linode-cli databases postgresql-list + https://api.linode.com/v4/object-storage/transfer/ + x-linode-cli-skip: true + x-original-op-id: getObjectStorageTransfer + x-original-op-title: Object Storage Transfer + View + /placement/groups: + x-akamai: + file-path: paths/groups.yaml + path-info: /placement/groups post: + x-linode charge: true + x-linode grant: add_placement + operationId: post-placement-group + summary: Create placement group 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. + - Placement groups + description: |- + Creates a placement group on your account. Placement groups let you set the physical location of your compute instances in a data center (region) to best suit your need. - Restricted Users must have the `add_databases` grant to use this command. + - For this request to complete successfully, your user must have the `add_placement` grant. + - We offer an [example API workflow](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/#create-a-placement-group) you can follow to create a placement group. - New instances can take approximately 15 to 30 minutes to provision. + __Note__. With the beta release, this service is only available in [select regions](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/#availability). - 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. + - __CLI__. - 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. + ``` + linode-cli placement group-create + ``` - 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. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - * 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. + - __OAuth__. - * **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. + ``` + linodes:read_write + ``` - * 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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli placement group-create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the Managed PostgreSQL Database you are creating. - x-linode-cli-allowed-defaults: - - engine - - region - - type + description: | + The requested initial state of the new placement group. required: true content: application/json: schema: - $ref: '#/components/schemas/DatabasePostgreSQLRequest' + type: object + required: + - affinity_type + - is_strict + - label + - region + allOf: + - type: object + description: | + Common properties for creating and rebuilding placement groups. + x-akamai: + file-path: schemas/placement-group-request.yaml + additionalProperties: false + properties: + affinity_type: + type: string + description: |- + Determine how compute instances are to be distributed in your placement group. Set to `anti-affinity:local` to place compute instances in separate fault domains, but still in the same region. This better supports a high-availability model. + + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: + - anti_affinity:local + enum: + - anti_affinity:local + x-linode-cli-display: 1 + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict, You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + + __Note__: Once you create a placement group, you can't change its `is_strict` setting. + example: true + label: + type: string + description: |- + A unique name for the placement group. A placement group `label` has the following constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`), or periods (`.`). + example: PG_Miami_failover + minLength: 1 + region: + type: string + description: | + The data center that houses the compute instances you want to add to your placement + group. Run the [List Linodes](https://techdocs.akamai.com/linode-api/reference/get-linode-instances) + operation to view your compute instances and store the `region` + identifier. + example: us-iad + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + x-linode-cli-allowed-defaults: + - affinity_type + - is_strict + - label + - region responses: - '200': - description: A new Managed PostgreSQL Database is provisioning. + default: + description: | + Error 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.** + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A new placement group is being created. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. - Display information for a single, accessible Managed PostgreSQL Database. + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is available + and all the compute instances in your group meet your `affinity_type` + and `is_strict` enforcement setting. If `false`, the group is + unavailable. One or more compute instances violate your `affinity_type` + and `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute instance + makes the group non-compliant. You need to wait for our + assistance to physically move it to meet your model, once + applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-placement-group 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' + - linodes:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/123 + source: |- + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "label": "PG_Miami_failover", + "region": "us-mia", + "affinity_type": "anti-affinity:local", + "is_strict": true + }' \ + https://api.linode.com/v4/placement/groups - lang: CLI - source: > - linode-cli databases postgresql-view 123 - delete: + source: |- + linode-cli placement create \ + --label PG_Miami_failover \ + --region us-mia \ + --affinity_type "anti-affinity:local" \ + --is_strict true + x-linode-cli-action: group-create + x-original-op-id: createPlacementGroup + x-original-op-title: Placement Group Create + get: + operationId: get-placement-groups + summary: List placement groups 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.** + - Placement groups + description: |- + Returns a paginated list of placement groups you have permission to view. - 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 + - __OAuth__. + + ``` + placement:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: placement:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} responses: - '200': - description: Managed PostgreSQL Database successfully deleted. + default: + description: | + Error content: application/json: schema: type: object - default: - $ref: '#/components/responses/ErrorResponse' + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns an array of all placement groups on your Account. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations + impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. + + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is + available and all the compute instances in your group + meet your `affinity_type` and `is_strict` enforcement + setting. If `false`, the group is unavailable. One or + more compute instances violate your `affinity_type` and + `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group + compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute + instance makes the group non-compliant. You need + to wait for our assistance to physically move it + to meet your model, once applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) + where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-placement-groups + security: + - personalAccessToken: [] + - oauth: + - placement:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - -X DELETE \ - https://api.linode.com/v4/databases/postgresql/instances/123 + https://api.linode.com/v4/placement/groups - 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 + source: linode-cli placement-list + x-linode-cli-action: + - groups-list + - groups-ls + x-original-op-id: getPlacementGroups + x-original-op-title: Placement Groups List + x-linode-cli-command: placement + /placement/groups/{groupId}: + x-akamai: + file-path: paths/group.yaml + path-info: /placement/groups/{groupId} + parameters: + - name: groupId + in: path 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. + ID of the placement group to look up. Run the [List placement groups](https://techdocs.akamai.com/linode-api/reference/get-placement-groups) + operation and store the `id` for the applicable placement group. + example: '{{groupId}}' + x-akamai: + file-path: parameters/group-id-path-043ea725.yaml + required: true + schema: + type: integer + get: + operationId: get-placement-group + summary: Get a placement group + tags: + - Placement groups + description: |- + View a specific placement group by ID. - 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. + - __CLI__. - * Entering an empty array (`[]`) blocks all connections (both public and private) to the Managed Database. + ``` + linode-cli placement group-view + ``` - * **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. + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) - 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. + - __OAuth__. - * 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. + ``` + linodes:read_only + ``` - * **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 + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli placement group-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: linodes:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] 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 + application/json: {} responses: - '200': - description: Managed Database updated successfully. + 200: + description: | + Returns a single placement group object. 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. + type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. - The Database must not be provisioning to perform this command. + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is available + and all the compute instances in your group meet your `affinity_type` + and `is_strict` enforcement setting. If `false`, the group is + unavailable. One or more compute instances violate your `affinity_type` + and `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: - Database `auto` type backups are created every 24 hours at 0:00 UTC. Each `auto` backup is retained for 7 days. + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: - 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. + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute instance + makes the group non-compliant. You need to wait for our + assistance to physically move it to meet your model, once + applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-placement-group 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' + - linodes:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/123/backups + -X GET \ + https://api.linode.com/v4/placement/groups/528 - lang: CLI - source: > - linode-cli databases postgresql-backups-list 123 - post: + source: linode-cli placement view 528 + x-linode-cli-action: group-view + x-linode-grant: read-only + x-original-op-id: getPlacementGroup + x-original-op-title: Placement Group View + put: + operationId: put-placement-group + summary: Update a placement group 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.** + - Placement groups + description: |- + Change the `label` for a specific placement group. This is the only value you can update. However, you can [add](#placement-group-add-linode) more compute instances or [remove](#placement-group-remove-linode) existing ones. - 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. + - __CLI__. - 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 + ``` + linode-cli placement group-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli placement group-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the snapshot backup to create. + description: | + Include the `label` parameter to update the name of your placement group. + required: true content: application/json: schema: - $ref: '#/components/schemas/DatabaseBackupSnapshot' + type: object + additionalProperties: false + properties: + label: + type: string + description: |- + A unique name for the placement group. A placement group `label` has the following constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`), or periods (`.`). + example: '{{label}}' + minLength: 1 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Database snapshot backup request successful. + default: + description: | + Error 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.** + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The updated placement group. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. - Display information for a single backup for an accessible Managed PostgreSQL Database. + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is available + and all the compute instances in your group meet your `affinity_type` + and `is_strict` enforcement setting. If `false`, the group is + unavailable. One or more compute instances violate your `affinity_type` + and `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: - The Database must not be provisioning to perform this command. + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute instance + makes the group non-compliant. You need to wait for our + assistance to physically move it to meet your model, once + applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-placement-group 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' + - linodes:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/123/backups/456 + source: |- + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X PUT -d '{ + "label": "PG_Miami_failover_update" + }' \ + https://api.linode.com/v4/placement/groups/528 - lang: CLI - source: > - linode-cli databases postgresql-backup-view 123 456 + source: |- + linode-cli placement update 528 \ + --label PG_Miami_failover_update + x-linode-cli-action: group-update + x-linode-grant: read-write + x-original-op-id: updatePlacementGroup + x-original-op-title: Placement Group Update delete: + operationId: delete-placement-group + summary: Delete a placement group 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.** + - Placement groups + description: |- + Deletes a placement group you have permission to `read_write`. - Delete a single backup for an accessible Managed PostgreSQL Database. + - Deleting a placement group can't be undone. + - All compute instances need to be [removed](https://techdocs.akamai.com/linode-api/reference/post-group-unassign) before you can delete a placement group. + - If your placement group is non-compliant, you can't delete it. You need to wait for our help to bring it [compliant](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/#non-compliance-precedence). - Requires `read_write` access to the Database. - The Database must not be provisioning to perform this command. - security: - - personalAccessToken: [] - - oauth: - - databases:read_write + --- + + + - __OAuth__. + + ``` + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Request to delete Database backup successful. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 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 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. + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-placement-group 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' + - linodes:read_write x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/123/credentials/ + -X DELETE \ + https://api.linode.com/v4/placement/groups/528 - lang: CLI - source: > - linode-cli databases postgresql-creds-view 123 - /databases/postgresql/instances/{instanceId}/credentials/reset: - x-linode-cli-command: databases + source: linode-cli placement delete 528 + x-linode-cli-action: + - group-delete + - group-rm + x-linode-grant: read_write + x-original-op-id: deletePlacementGroup + x-original-op-title: Placement Group Delete + x-linode-cli-command: placement + /placement/groups/{groupId}/assign: + x-akamai: + file-path: paths/group-assign.yaml + path-info: /placement/groups/{groupId}/assign parameters: - - name: instanceId - in: path - description: The ID of the Managed PostgreSQL Database. - required: true - schema: - type: integer + - name: groupId + in: path + description: |- + ID of the placement group to look up. Run the [List placement groups](https://techdocs.akamai.com/linode-api/reference/get-placement-groups) operation and store the `id` + for the applicable placement group. + example: '{{groupId}}' + x-akamai: + file-path: parameters/group-id-path.yaml + required: true + schema: + type: integer post: + operationId: post-group-add-linode + summary: Assign a placement group 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.** + - Placement groups + description: |- + Add one or more compute instances to your placement group. Check out our [example API workflow](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/#create-a-placement-group) to create a placement group and add compute instances. - 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. + - __CLI__. - **Note**: Note that it may take several seconds for credentials to reset. - security: - - personalAccessToken: [] - - oauth: - - databases:read_write + ``` + linode-cli placement assign-linode + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli placement assign-linode + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The compute instances you want to add to your placement group. + required: true + content: + application/json: + schema: + type: object + description: | + The compute instances included in a placement group. + x-akamai: + file-path: schemas/placement-group-compute-instances.yaml + additionalProperties: false + properties: + linodes: + type: array + description: | + The `linodeId` values for individual compute instances included in the placement group. + example: 528 + items: + type: integer + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Managed Database instance credentials successfully reset. + default: + description: | + Error 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.** + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The compute instance was added successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. - Display the SSL CA certificate for an accessible Managed PostgreSQL Database. + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is available + and all the compute instances in your group meet your `affinity_type` + and `is_strict` enforcement setting. If `false`, the group is + unavailable. One or more compute instances violate your `affinity_type` + and `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: - The Database must have an `active` status to perform this command. + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute instance + makes the group non-compliant. You need to wait for our + assistance to physically move it to meet your model, once + applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-group-add-linode 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' + - linodes:read_write x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/databases/postgresql/instances/123/ssl + source: |- + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "linode": [123, 456], + "non-compliant": false + }' \ + https://api.linode.com/v4/placement/groups/528/assign - lang: CLI - source: > - linode-cli databases postgresql-ssl-cert 123 - /databases/postgresql/instances/{instanceId}/patch: - x-linode-cli-command: databases + source: |- + linode-cli placement assignLinode 528 \ + --linodes 123 456 \ + --non-compliant true + x-linode-cli-action: assign-linode + x-linode-grant: read-write + x-original-op-id: placementGroupAddLinode + x-original-op-title: Placement Group Assign + x-linode-cli-command: placement + /placement/groups/{groupId}/unassign: + x-akamai: + file-path: paths/unassign.yaml + path-info: /placement/groups/{groupId}/unassign parameters: - - name: instanceId - in: path - description: The ID of the Managed PostgreSQL Database. - required: true - schema: - type: integer + - name: groupId + in: path + description: | + ID of the placement group to look up. Run the [List placement groups](https://techdocs.akamai.com/linode-api/reference/get-placement-groups) + operation and store the `id` for the applicable placement group. + example: '{{groupId}}' + x-akamai: + file-path: parameters/group-id-path-0d373f63.yaml + required: true + schema: + type: integer + x-ref: ../schemas/added-tbd.yaml post: + operationId: post-group-unassign + summary: Unassign a placement group 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.** + - Placement groups + description: |- + Remove one or more compute instances from your placement group. - 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** + - __CLI__. - * 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. + ``` + linode-cli placement unassign-linode + ``` - * **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 + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli placement unassign-linode + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The compute instances you want to remove from your placement group. + required: true + content: + application/json: + schema: + type: array + description: | + The `linodeId` values for individual compute instances included in the placement group. + example: 528 + items: + type: integer + x-example: + x-ref: ../examples/tbd.json responses: - '200': - description: Managed Database instance patch request successful. + default: + description: | + Error 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. + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The compute instance was removed successfully. content: application/json: - x-linode-cli-nested-list: engines.mysql, engines.postgresql - x-linode-cli-use-schema: + schema: type: object + x-akamai: + file-path: schemas/placement-group.yaml + additionalProperties: false properties: id: + type: integer + description: | + The placement group's ID. You need to provide it for all operations impacting it. + example: 528 + nullable: false x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. + + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_compliant: + type: boolean + description: | + The availability of the placement group. `true` indicates the group is available + and all the compute instances in your group meet your `affinity_type` + and `is_strict` enforcement setting. If `false`, the group is + unavailable. One or more compute instances violate your `affinity_type` + and `is_strict` settings. You need to wait for our assistance + to physically move compute instances to make the group compliant. + example: true + nullable: false + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false 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' + type: string + description: |- + The unique name set for the placement group. A label has these constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + members: + type: array + description: | + An array of compute instances included in the placement group. + items: + type: object + additionalProperties: false + properties: + is_compliant: + type: boolean + description: | + Whether or not the compute instance meets your group's `affinity_type` + and `is_strict` settings. If `false`, the compute instance + makes the group non-compliant. You need to wait for our + assistance to physically move it to meet your model, once + applicable space is available. + example: true + linode_id: + type: integer + description: | + __Read-only__ The unique identifier for a compute instance included + in the placement group. + example: 123 + readOnly: true + region: + type: string + description: | + __Read-only__ The [region](https://techdocs.akamai.com/linode-api/reference/get-regions) where the placement group was deployed. + example: us-mia + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-group-unassign + security: + - personalAccessToken: [] + - oauth: + - linodes:read_write x-code-samples: - lang: Shell - source: > - curl https://api.linode.com/v4/databases/types + source: |- + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -X POST -d '{ + "linode": [123, 456] + }' \ + https://api.linode.com/v4/placement/groups/528/unassign - 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 + source: |- + linode-cli placement unassignLinode 528 \ + --linode 123 456 + x-linode-cli-action: unassign-linode + x-linode-grant: read-write + x-original-op-id: post-group-unassign + x-original-op-title: Placement Group Unassign + x-linode-cli-command: placement + /profile: + x-akamai: + file-path: paths/profile.yaml + path-info: /profile get: + operationId: get-profile + summary: Get a profile 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.** + - Profile + 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. - 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. + This operation is always accessible, no matter what OAuth scopes the acting token has. + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: Returns a single Managed Database type. + default: + description: | + Error content: application/json: - x-linode-cli-nested-list: engines.mysql, engines.postgresql - x-linode-cli-use-schema: + schema: type: object + additionalProperties: false 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. + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Profile response. content: application/json: schema: type: object + description: | + A Profile represents your User in our system. This is where you can change information about + your User. This information is available to any OAuth Client regardless + of requested scopes, and can be used to populate User information + in third-party applications. + x-akamai: + file-path: schemas/profile.yaml + additionalProperties: false properties: - data: + authentication_type: + type: string + description: |- + __Read-only__ This account's Cloud Manager authentication type. Authentication types are chosen through Cloud Manager and authorized when logging into your account. These authentication types are either the user's password (in conjunction with their username), or the name of their identity provider such as GitHub. For example, if a user: + + - Has never used Third-Party Authentication, their authentication type will be `password`. + - Is using Third-Party Authentication, their authentication type will be the name of their Identity Provider (eg. `github`). + - Has used Third-Party Authentication and has since revoked it, their authentication type will be `password`. + + __Note:__ This functionality may not yet be available in Cloud Manager. See the [Cloud Manager Changelog](https://www.linode.com/docs/products/tools/cloud-manager/release-notes/) for the latest updates. + example: password + readOnly: true + enum: + - password + - github + authorized_keys: type: array + description: | + The list of SSH Keys authorized to use Lish for your User. This value is ignored + if `lish_auth_method` is "disabled." + example: null + nullable: true 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 + type: string + format: ssh-key + email: + type: string + description: | + Your email address. This address will be used for communication with Linode as necessary. + example: example-user@gmail.com + format: email + x-linode-cli-display: 2 + email_notifications: + type: boolean + description: | + If true, you will receive email notifications about account activity. If false, you may + still receive business-critical communications through email. + example: true + ip_whitelist_enabled: + type: boolean + description: | + If true, logins for your User will only be allowed from whitelisted IPs. This setting + is currently deprecated, and cannot be enabled. If you disable + this setting, you will not be able to re-enable it. + example: false + deprecated: true + lish_auth_method: + type: string + description: |- + The authentication methods that are allowed when connecting to [the Linode Shell (Lish)](https://www.linode.com/docs/guides/lish/). + + - `keys_only` is the most secure if you intend to use Lish. + - `disabled` is recommended if you do not intend to use Lish at all. + - If this account's Cloud Manager authentication type is set to a Third-Party Authentication method, `password_keys` cannot be used as your Lish authentication method. To view this account's Cloud Manager `authentication_type` field, send a request to the [Get a profile](https://techdocs.akamai.com/linode-api/reference/get-profile) operation. + example: keys_only + enum: + - password_keys + - keys_only + - disabled + referrals: + type: object + description: |- + __Read-only__ Information about your status in our referral program. + + This information becomes accessible after this Profile's Account has established at least $25.00 USD of total payments. + additionalProperties: false + readOnly: true + properties: + code: + type: string + description: | + __Read-only__ Your referral code. If others use this when signing up for Linode, + you will receive account credit. + example: 871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + completed: + type: integer + description: | + __Read-only__ The number of completed signups with your referral code. + example: 0 + readOnly: true + credit: + type: integer + description: | + __Read-only__ The amount of account credit in US Dollars issued to you through + the referral program. + example: 0 + readOnly: true + pending: + type: integer + description: | + __Read-only__ The number of pending signups with your referral code. You + will not receive credit for these signups until they are + completed. + example: 0 + readOnly: true + total: + type: integer + description: | + __Read-only__ The number of users who have signed up with your referral code. + example: 0 + readOnly: true + url: + type: string + description: | + __Read-only__ Your referral url, used to direct others to sign up for Linode + with your referral code. + example: https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + format: url + restricted: + type: boolean + description: | + If true, your User has restrictions on what can be accessed on your Account. To + get details on what entities/actions you can access/perform, + run [List grants](https://techdocs.akamai.com/linode-api/reference/get-profile-grants). + example: false + x-linode-cli-display: 3 + timezone: + type: string + description: | + The timezone you prefer to see times in. This is not used by the API directly. It is + provided for the benefit of clients such as the Linode Cloud + Manager and other clients built on the API. All times returned + by the API are in UTC. + example: US/Eastern + two_factor_auth: + type: boolean + description: | + If true, logins from untrusted computers will require Two Factor Authentication. Run + [Create a two factor secret](https://techdocs.akamai.com/linode-api/reference/post-tfa-enable) + to enable Two Factor Authentication. + example: true + x-linode-cli-display: 4 + uid: + type: integer + description: | + __Read-only__ Your unique ID in our system. This value will never change, and can + safely be used to identify your User. + example: 1234 + readOnly: true + username: + type: string + description: | + __Read-only__ Your username, used for logging in to our system. + example: exampleUser + readOnly: true + x-linode-cli-display: 1 + verified_phone_number: + type: string + description: |- + __Read-only__ The phone number verified for this Profile with the [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation. + + `null` if this Profile has no verified phone number. + example: '+5555555555' + nullable: true + readOnly: true + format: phone + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile security: - personalAccessToken: [] - - oauth: - - domains:read_write + - oauth: [] + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/profile + - lang: CLI + source: linode-cli profile view + x-linode-cli-action: view + x-original-op-id: getProfile + x-original-op-title: Profile View + put: + operationId: put-profile + summary: Update a profile + tags: + - Profile + description: |- + Update information in your Profile. This operation requires the "account:read_write" OAuth Scope. + + __Parent and child accounts__ + + In a [parent and child account](https://www.linode.com/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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] requestBody: - description: Information about the domain you are registering. + description: | + The fields to update. 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 + type: object + description: | + A Profile represents your User in our system. This is where you can change information about + your User. This information is available to any OAuth Client regardless + of requested scopes, and can be used to populate User information + in third-party applications. + x-akamai: + file-path: schemas/profile.yaml + additionalProperties: false + properties: + authentication_type: + type: string + description: |- + __Read-only__ This account's Cloud Manager authentication type. Authentication types are chosen through Cloud Manager and authorized when logging into your account. These authentication types are either the user's password (in conjunction with their username), or the name of their identity provider such as GitHub. For example, if a user: + + - Has never used Third-Party Authentication, their authentication type will be `password`. + - Is using Third-Party Authentication, their authentication type will be the name of their Identity Provider (eg. `github`). + - Has used Third-Party Authentication and has since revoked it, their authentication type will be `password`. + + __Note:__ This functionality may not yet be available in Cloud Manager. See the [Cloud Manager Changelog](https://www.linode.com/docs/products/tools/cloud-manager/release-notes/) for the latest updates. + example: '{{authentication_type}}' + readOnly: true + enum: + - password + - github + authorized_keys: + type: array + description: | + The list of SSH Keys authorized to use Lish for your User. This value is ignored if + `lish_auth_method` is "disabled." + example: null + nullable: true + items: + type: string + format: ssh-key + email: + type: string + description: | + Your email address. This address will be used for communication with Linode as necessary. + example: '{{email}}' + format: email + x-linode-cli-display: 2 + email_notifications: + type: boolean + description: | + If true, you will receive email notifications about account activity. If false, you may + still receive business-critical communications through email. + example: '{{email_notifications}}' + ip_whitelist_enabled: + type: boolean + description: | + If true, logins for your User will only be allowed from whitelisted IPs. This setting is + currently deprecated, and cannot be enabled. If you disable this + setting, you will not be able to re-enable it. + example: '{{ip_whitelist_enabled}}' + deprecated: true + lish_auth_method: + type: string + description: |- + The authentication methods that are allowed when connecting to [the Linode Shell (Lish)](https://www.linode.com/docs/guides/lish/). + + - `keys_only` is the most secure if you intend to use Lish. + - `disabled` is recommended if you do not intend to use Lish at all. + - If this account's Cloud Manager authentication type is set to a Third-Party Authentication method, `password_keys` cannot be used as your Lish authentication method. To view this account's Cloud Manager `authentication_type` field, send a request to the [Get a profile](https://techdocs.akamai.com/linode-api/reference/get-profile) operation. + example: '{{lish_auth_method}}' + enum: + - password_keys + - keys_only + - disabled + referrals: + type: object + description: |- + __Read-only__ Information about your status in our referral program. + + This information becomes accessible after this Profile's Account has established at least $25.00 USD of total payments. + additionalProperties: false + readOnly: true + properties: + code: + type: string + description: | + __Read-only__ Your referral code. If others use this when signing up for Linode, + you will receive account credit. + example: 871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + completed: + type: integer + description: | + __Read-only__ The number of completed signups with your referral code. + example: 0 + readOnly: true + credit: + type: integer + description: | + __Read-only__ The amount of account credit in US Dollars issued to you through + the referral program. + example: 0 + readOnly: true + pending: + type: integer + description: | + __Read-only__ The number of pending signups with your referral code. You will + not receive credit for these signups until they are completed. + example: 0 + readOnly: true + total: + type: integer + description: | + __Read-only__ The number of users who have signed up with your referral code. + example: 0 + readOnly: true + url: + type: string + description: | + __Read-only__ Your referral url, used to direct others to sign up for Linode + with your referral code. + example: https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + format: url + restricted: + type: boolean + description: | + If true, your User has restrictions on what can be accessed on your Account. To get details + on what entities/actions you can access/perform, run [List grants](https://techdocs.akamai.com/linode-api/reference/get-profile-grants). + example: '{{restricted}}' + x-linode-cli-display: 3 + timezone: + type: string + description: | + The timezone you prefer to see times in. This is not used by the API directly. It is provided + for the benefit of clients such as the Linode Cloud Manager and + other clients built on the API. All times returned by the API + are in UTC. + example: '{{timezone}}' + two_factor_auth: + type: boolean + description: | + If true, logins from untrusted computers will require Two Factor Authentication. Run + [Create a two factor secret](https://techdocs.akamai.com/linode-api/reference/post-tfa-enable) + to enable Two Factor Authentication. + example: '{{two_factor_auth}}' + x-linode-cli-display: 4 + uid: + type: integer + description: | + __Read-only__ Your unique ID in our system. This value will never change, and can safely + be used to identify your User. + example: '{{uid}}' + readOnly: true + username: + type: string + description: | + __Read-only__ Your username, used for logging in to our system. + example: '{{username}}' + readOnly: true + x-linode-cli-display: 1 + verified_phone_number: + type: string + description: |- + __Read-only__ The phone number verified for this Profile with the [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation. + + `null` if this Profile has no verified phone number. + example: '{{verified_phone_number}}' + nullable: true + readOnly: true + format: phone + x-example: + x-ref: ../examples/tbd.json responses: - '200': + default: description: | - A single Domain in Linode's DNS Manager. + Error 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. + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Profile updated successfully. content: application/json: schema: - $ref: '#/components/schemas/Domain' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + description: | + A Profile represents your User in our system. This is where you can change information about + your User. This information is available to any OAuth Client regardless + of requested scopes, and can be used to populate User information + in third-party applications. + x-akamai: + file-path: schemas/profile.yaml + additionalProperties: false + properties: + authentication_type: + type: string + description: |- + __Read-only__ This account's Cloud Manager authentication type. Authentication types are chosen through Cloud Manager and authorized when logging into your account. These authentication types are either the user's password (in conjunction with their username), or the name of their identity provider such as GitHub. For example, if a user: + + - Has never used Third-Party Authentication, their authentication type will be `password`. + - Is using Third-Party Authentication, their authentication type will be the name of their Identity Provider (eg. `github`). + - Has used Third-Party Authentication and has since revoked it, their authentication type will be `password`. + + __Note:__ This functionality may not yet be available in Cloud Manager. See the [Cloud Manager Changelog](https://www.linode.com/docs/products/tools/cloud-manager/release-notes/) for the latest updates. + example: password + readOnly: true + enum: + - password + - github + authorized_keys: + type: array + description: | + The list of SSH Keys authorized to use Lish for your User. This value is ignored + if `lish_auth_method` is "disabled." + example: null + nullable: true + items: + type: string + format: ssh-key + email: + type: string + description: | + Your email address. This address will be used for communication with Linode as necessary. + example: example-user@gmail.com + format: email + x-linode-cli-display: 2 + email_notifications: + type: boolean + description: | + If true, you will receive email notifications about account activity. If false, you may + still receive business-critical communications through email. + example: true + ip_whitelist_enabled: + type: boolean + description: | + If true, logins for your User will only be allowed from whitelisted IPs. This setting + is currently deprecated, and cannot be enabled. If you disable + this setting, you will not be able to re-enable it. + example: false + deprecated: true + lish_auth_method: + type: string + description: |- + The authentication methods that are allowed when connecting to [the Linode Shell (Lish)](https://www.linode.com/docs/guides/lish/). + + - `keys_only` is the most secure if you intend to use Lish. + - `disabled` is recommended if you do not intend to use Lish at all. + - If this account's Cloud Manager authentication type is set to a Third-Party Authentication method, `password_keys` cannot be used as your Lish authentication method. To view this account's Cloud Manager `authentication_type` field, send a request to the [Get a profile](https://techdocs.akamai.com/linode-api/reference/get-profile) operation. + example: keys_only + enum: + - password_keys + - keys_only + - disabled + referrals: + type: object + description: |- + __Read-only__ Information about your status in our referral program. + + This information becomes accessible after this Profile's Account has established at least $25.00 USD of total payments. + additionalProperties: false + readOnly: true + properties: + code: + type: string + description: | + __Read-only__ Your referral code. If others use this when signing up for Linode, + you will receive account credit. + example: 871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + completed: + type: integer + description: | + __Read-only__ The number of completed signups with your referral code. + example: 0 + readOnly: true + credit: + type: integer + description: | + __Read-only__ The amount of account credit in US Dollars issued to you through + the referral program. + example: 0 + readOnly: true + pending: + type: integer + description: | + __Read-only__ The number of pending signups with your referral code. You + will not receive credit for these signups until they are + completed. + example: 0 + readOnly: true + total: + type: integer + description: | + __Read-only__ The number of users who have signed up with your referral code. + example: 0 + readOnly: true + url: + type: string + description: | + __Read-only__ Your referral url, used to direct others to sign up for Linode + with your referral code. + example: https://www.linode.com/?r=871be32f49c1411b14f29f618aaf0c14637fb8d3 + readOnly: true + format: url + restricted: + type: boolean + description: | + If true, your User has restrictions on what can be accessed on your Account. To + get details on what entities/actions you can access/perform, + run [List grants](https://techdocs.akamai.com/linode-api/reference/get-profile-grants). + example: false + x-linode-cli-display: 3 + timezone: + type: string + description: | + The timezone you prefer to see times in. This is not used by the API directly. It is + provided for the benefit of clients such as the Linode Cloud + Manager and other clients built on the API. All times returned + by the API are in UTC. + example: US/Eastern + two_factor_auth: + type: boolean + description: | + If true, logins from untrusted computers will require Two Factor Authentication. Run + [Create a two factor secret](https://techdocs.akamai.com/linode-api/reference/post-tfa-enable) + to enable Two Factor Authentication. + example: true + x-linode-cli-display: 4 + uid: + type: integer + description: | + __Read-only__ Your unique ID in our system. This value will never change, and can + safely be used to identify your User. + example: 1234 + readOnly: true + username: + type: string + description: | + __Read-only__ Your username, used for logging in to our system. + example: exampleUser + readOnly: true + x-linode-cli-display: 1 + verified_phone_number: + type: string + description: |- + __Read-only__ The phone number verified for this Profile with the [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation. + + `null` if this Profile has no verified phone number. + example: '+5555555555' + nullable: true + readOnly: true + format: phone + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-profile + security: + - personalAccessToken: [] + - oauth: + - account:read_write x-code-samples: - lang: Shell - source: > + 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"] + "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/domains/123 + https://api.linode.com/v4/profile - lang: CLI - source: > - linode-cli domains update 1234 \ - --retry_sec 7200 \ - --ttl_sec 300 - delete: - x-linode-grant: read_write + 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 + x-linode-cli-action: update + x-original-op-id: updateProfile + x-original-op-title: Profile Update + x-linode-cli-command: profile + /profile/apps: + x-akamai: + file-path: paths/apps.yaml + path-info: /profile/apps + get: + operationId: get-profile-apps + summary: List authorized apps 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 + - Apps + description: |- + This is a collection of OAuth apps that you've given access to your Account, and includes the level of access granted. + + + --- + + + - __CLI__. + + ``` + linode-cli profile apps-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile apps-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} responses: - '200': - description: Domain deleted successfully. + default: + description: | + Error 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 + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of apps you've authorized. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An application you have authorized access to your Account through OAuth. + x-akamai: + file-path: schemas/authorized-app.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This authorization's ID, used for revoking access. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ When this app was authorized. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 5 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When the app's access to your account expires. If `null`, + the app's access must be revoked manually. + example: '2018-01-15T00:01:01' + nullable: true + readOnly: true + format: date-time + x-linode-cli-display: 6 + x-linode-filterable: true + label: + type: string + description: | + __Read-only__ The name of the application you've authorized. + example: example-app + readOnly: true + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The OAuth scopes this app was authorized with. This defines + what parts of your Account the app is allowed to access. + example: linodes:read_only + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + thumbnail_url: + type: string + description: | + __Read-only__ The URL at which this app's thumbnail may be accessed. + example: null + readOnly: true + format: url + website: + type: string + description: | + __Read-only__ The website where you can get more information about this + app. + example: example.org + readOnly: true + format: url + x-linode-cli-display: 4 + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile-apps + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: apps-list + x-original-op-id: getProfileApps + x-original-op-title: Authorized Apps List + x-linode-cli-command: profile + /profile/apps/{appId}: + x-akamai: + file-path: paths/app.yaml + path-info: /profile/apps/{appId} parameters: - - name: domainId + - name: appId in: path - description: ID of the Domain. + description: | + The authorized app ID to manage. + example: '{{appId}}' + x-akamai: + file-path: parameters/app-id-path.yaml required: true schema: - type: string + type: integer get: - x-linode-grant: read_only + operationId: get-profile-app + summary: Get an authorized app 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 + - Apps + description: |- + Returns information about a single app you've authorized to access your Account. + + + --- + + + - __CLI__. + + ``` + linode-cli profile app-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile app-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': + default: description: | - An array containing the lines of the domain zone file. + Error content: application/json: schema: + type: object + additionalProperties: false properties: - zone_file: + errors: 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." + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The app requested. + content: + application/json: + schema: + type: object + description: | + An application you have authorized access to your Account through OAuth. + x-akamai: + file-path: schemas/authorized-app.yaml + additionalProperties: false + properties: + id: + type: integer description: | - The lines of the zone file for the last rendered zone for this domain. - default: - $ref: '#/components/responses/ErrorResponse' + __Read-only__ This authorization's ID, used for revoking access. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ When this app was authorized. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 5 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When the app's access to your account expires. If `null`, the app's + access must be revoked manually. + example: '2018-01-15T00:01:01' + nullable: true + readOnly: true + format: date-time + x-linode-cli-display: 6 + x-linode-filterable: true + label: + type: string + description: | + __Read-only__ The name of the application you've authorized. + example: example-app + readOnly: true + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The OAuth scopes this app was authorized with. This defines what parts + of your Account the app is allowed to access. + example: linodes:read_only + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + thumbnail_url: + type: string + description: | + __Read-only__ The URL at which this app's thumbnail may be accessed. + example: null + readOnly: true + format: url + website: + type: string + description: | + __Read-only__ The website where you can get more information about this app. + example: example.org + readOnly: true + format: url + x-linode-cli-display: 4 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile-app + security: + - personalAccessToken: [] + - oauth: + - account:read_only x-code-samples: - lang: Shell - source: > + source: |- curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/domains/123/zone-file + https://api.linode.com/v4/profile/apps/123 - 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 + source: linode-cli profile app-view 1234 + x-linode-cli-action: app-view + x-original-op-id: getProfileApp + x-original-op-title: Authorized App View + delete: + operationId: delete-profile-app + summary: Revoke app access tags: - - Domains - summary: Domain Import - description: > - Imports a domain zone from a remote nameserver. + - Apps + description: |- + Expires this app token. This token may no longer be used to access your Account. - 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 + --- + + + - __CLI__. + + ``` + linode-cli profile app-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile app-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] 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 + application/json: {} responses: - '200': + default: description: | - A single Domain in Linode's DNS Manager. + Error 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': + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: description: | - A new Domain in Linode's DNS Manager, based on a cloned Domain. + App's authorization has been revoked. content: application/json: schema: - $ref: '#/components/schemas/Domain' - default: - $ref: '#/components/responses/ErrorResponse' + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-profile-app + security: + - personalAccessToken: [] + - oauth: + - account:read_write 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 + 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 + x-linode-cli-action: app-delete + x-original-op-id: deleteProfileApp + x-original-op-title: App Access Revoke + x-linode-cli-command: profile + /profile/devices: + x-akamai: + file-path: paths/profile-devices.yaml + path-info: /profile/devices + get: + operationId: get-devices + summary: List trusted devices + tags: + - Devices + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile devices-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile devices-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of TrustedDevice objects. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A trusted device object represents an active Remember Me session with [login.linode.com](https://login.linode.com). + x-akamai: + file-path: schemas/trusted-device.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID for this TrustedDevice + example: 123 + readOnly: true + created: + type: string + description: | + __Read-only__ When this Remember Me session was started. This corresponds + to the time of login with the "Remember Me" box checked. + example: '2018-01-01T01:01:01' + readOnly: true + format: date-time + expiry: + type: string + description: | + __Read-only__ When this TrustedDevice session expires. Sessions typically + last 30 days. + example: '2018-01-31T01:01:01' + readOnly: true + format: date-time + last_authenticated: + type: string + description: | + __Read-only__ The last time this TrustedDevice was successfully used + to authenticate to [login.linode.com](https://login.linode.com). + example: '2018-01-05T12:57:12' + readOnly: true + format: date-time + last_remote_addr: + type: string + description: | + __Read-only__ The last IP Address to successfully authenticate with + this TrustedDevice. + example: 203.0.113.1 + readOnly: true + user_agent: + type: string + description: | + __Read-only__ The User Agent of the browser that created this TrustedDevice + session. + example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like + Gecko) Chrome/70.0.3538.77 Safari/537.36 Vivaldi/2.1.1337.36 + readOnly: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-devices + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: devices-list + x-original-op-id: getDevices + x-original-op-title: Trusted Devices List + x-linode-cli-command: profile + /profile/devices/{deviceId}: + x-akamai: + file-path: paths/profile-device.yaml + path-info: /profile/devices/{deviceId} parameters: - - name: domainId + - name: deviceId in: path - description: The ID of the Domain we are accessing Records for. + description: | + The ID of the TrustedDevice + example: '{{deviceId}}' + x-akamai: + file-path: parameters/device-id-path-b3b3e692.yaml required: true schema: type: integer get: - x-linode-grant: read_only + operationId: get-trusted-device + summary: Get a trusted device 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 + - Devices + description: |- + Returns a single active TrustedDevice for your User. + + + --- + + + - __CLI__. + + ``` + linode-cli profile device-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile device-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} responses: - '200': - description: A list of Domain Records. + default: + description: | + Error content: application/json: schema: type: object + additionalProperties: false properties: - data: + errors: 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' + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested TrustedDevice object + content: + application/json: + schema: + type: object + description: | + A trusted device object represents an active Remember Me session with [login.linode.com](https://login.linode.com). + x-akamai: + file-path: schemas/trusted-device.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID for this TrustedDevice + example: 123 + readOnly: true + created: + type: string + description: | + __Read-only__ When this Remember Me session was started. This corresponds to the + time of login with the "Remember Me" box checked. + example: '2018-01-01T01:01:01' + readOnly: true + format: date-time + expiry: + type: string + description: | + __Read-only__ When this TrustedDevice session expires. Sessions typically last + 30 days. + example: '2018-01-31T01:01:01' + readOnly: true + format: date-time + last_authenticated: + type: string + description: | + __Read-only__ The last time this TrustedDevice was successfully used to authenticate + to [login.linode.com](https://login.linode.com). + example: '2018-01-05T12:57:12' + readOnly: true + format: date-time + last_remote_addr: + type: string + description: | + __Read-only__ The last IP Address to successfully authenticate with this TrustedDevice. + example: 203.0.113.1 + readOnly: true + user_agent: + type: string + description: | + __Read-only__ The User Agent of the browser that created this TrustedDevice session. + example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) + Chrome/70.0.3538.77 Safari/537.36 Vivaldi/2.1.1337.36 + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-trusted-device + security: + - personalAccessToken: [] + - oauth: + - account:read_only x-code-samples: - lang: Shell - source: > - curl -H "Authorization: Bearer $TOKEN" \ - https://api.linode.com/v4/domains/1234/records + source: |- + curl -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/profile/devices/123 - lang: CLI - source: > - linode-cli domains records-list 1234 - post: - x-linode-grant: read_write + source: linode-cli profile device-view 123 + x-linode-cli-action: device-view + x-original-op-id: getTrustedDevice + x-original-op-title: Trusted Device View + delete: + operationId: delete-trusted-device + summary: Revoke a trusted device tags: - - Domains + - Devices + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile device-revoke + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile device-revoke + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Session revoked successfully + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-trusted-device security: - personalAccessToken: [] - oauth: - - domains:read_write - summary: Domain Record Create - description: | - Adds a new Domain Record to the zonefile this Domain represents. + - account:read_write + 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 + x-linode-cli-action: device-revoke + x-original-op-id: revokeTrustedDevice + x-original-op-title: Trusted Device Revoke + x-linode-cli-command: profile + /profile/grants: + x-akamai: + file-path: paths/profile-grants.yaml + path-info: /profile/grants + get: + operationId: get-profile-grants + summary: List grants + tags: + - Grants + 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 operation 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 run this operation; no OAuth scopes are required. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + GrantsResponse + content: + application/json: + schema: + type: object + description: | + A structure representing all grants a restricted User has on the Account. Not available for + unrestricted users, as they have access to everything without grants. + If retrieved from the `/profile/grants` endpoint, entities to which + a User has no access will be omitted. + x-akamai: + file-path: schemas/grants-response.yaml + additionalProperties: false + properties: + database: + type: array + description: | + The grants this User has for each Database that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + domain: + type: array + description: | + The grants this User has for each Domain that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + global: + type: object + description: | + A structure containing the Account-level grants a User has. + additionalProperties: false + properties: + account_access: + type: string + description: |- + The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users. + + __Parent and child accounts__ + + In a [parent and child account](https://www.linode.com/docs/guides/parent-child-accounts/) environment, this grant can be added to a child account user, to give the user `read-write` access. This gives the child user unrestricted access to expected management operations, such as creating other child users. However, child users don't have write access to billing operations. The API issues a specific error message if a write operation is attempted by a child user. + example: read_only + nullable: true + enum: + - read_only + - read_write + add_databases: + type: boolean + description: | + If true, this User may add Managed Databases. + example: true + add_domains: + type: boolean + description: | + If true, this User may add Domains. + example: true + add_firewalls: + type: boolean + description: | + If true, this User may add Firewalls. + example: true + add_images: + type: boolean + description: | + If true, this User may add Images. + example: true + add_linodes: + type: boolean + description: | + If true, this User may create Linodes. + example: true + add_loadbalancers: + type: boolean + description: | + If true, this User may add Cloud Load Balancers. + example: true + add_longview: + type: boolean + description: | + If true, this User may create Longview clients and view the current plan. + example: true + add_nodebalancers: + type: boolean + description: | + If true, this User may add NodeBalancers. + example: true + add_stackscripts: + type: boolean + description: | + If true, this User may add StackScripts. + example: true + add_volumes: + type: boolean + description: | + If true, this User may add Volumes. + example: true + add_vpcs: + type: boolean + description: | + If true, this User may add VPCs. + example: true + cancel_account: + type: boolean + description: | + If true, this User may cancel the entire Account. + example: false + child_account_access: + type: boolean + description: | + In a [parent and child account](https://www.linode.com/docs/guides/parent-child-accounts/) + environment, this gives a parent account access to endpoints + that can be used to manage child accounts. Unrestricted + parent account users have access to this grant, while restricted + parent users don't. An unrestricted parent user can set + this to `true` to add this grant to a restricted parent + user. Displayed as `null` for all non-parent accounts. + example: true + nullable: true + longview_subscription: + type: boolean + description: | + If true, this User may manage the Account's Longview subscription. + example: true + image: + type: array + description: | + The grants this User has for each Image that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + linode: + type: array + description: | + The grants this User has for each Linode that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + loadbalancer: + type: array + description: | + The grants this User has for each Cloud Load Balancer that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + longview: + type: array + description: | + The grants this User has for each Longview Client that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + nodebalancer: + type: array + description: | + The grants this User has for each NodeBalancer that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + stackscript: + type: array + description: | + The grants this User has for each StackScript that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + volume: + type: array + description: | + The grants this User has for each Block Storage Volume that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + vpc: + type: array + description: | + The grants this User has for each VPC that is owned by this Account. + items: + type: object + description: | + Represents the level of access a restricted User has to a specific resource on + the Account. + x-akamai: + file-path: schemas/grant.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + The ID of the entity this grant applies to. + example: 123 + label: + type: string + description: | + __Read-only__ The current label of the entity this grant applies to, + for display purposes. + example: example-entity + readOnly: true + permissions: + type: string + description: | + The level of access this User has to this entity. If null, this User + has no access. + example: read_only + nullable: true + enum: + - read_only + - read_write + x-example: + x-ref: ../examples/tbd.json + 204: + description: | + This is an unrestricted User, who has no grants. This User can access everything on the Account. + content: + application/json: {} + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile-grants + security: + - personalAccessToken: [] + - oauth: [] + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/profile/grants + x-linode-cli-action: grants + x-linode-cli-skip: true + x-original-op-id: getProfileGrants + x-original-op-title: Grants List + x-linode-cli-command: profile + /profile/logins: + x-akamai: + file-path: paths/profile-logins.yaml + path-info: /profile/logins + get: + operationId: get-profile-logins + summary: List logins + tags: + - Logins + description: |- + Returns a collection of successful account logins from this user during the last 90 days. + + + --- + + + - __CLI__. + + ``` + linode-cli profile logins-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile logins-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + An array of successful account logins from this user during the last 90 days. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An object representing a previous successful login for a User. + x-akamai: + file-path: schemas/login.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this login object. + example: 1234 + readOnly: true + x-linode-cli-display: 1 + datetime: + type: string + description: | + __Read-only__ When the login was initiated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 2 + ip: + type: string + description: | + __Read-only__ The remote IP address that requested the login. + example: 192.0.2.0 + readOnly: true + format: ip + x-linode-cli-display: 3 + restricted: + type: boolean + description: | + __Read-only__ True if the User that attempted the login was a restricted + User, false otherwise. + example: true + readOnly: true + x-linode-cli-display: 6 + status: + type: string + description: | + __Read-only__ Whether the login attempt succeeded or failed. + example: successful + readOnly: true + enum: + - successful + - failed + x-linode-cli-display: 5 + username: + type: string + description: | + __Read-only__ The username of the User that attempted the login. + example: example_user + readOnly: true + x-linode-cli-display: 4 + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile-logins + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: logins-list + x-original-op-id: getProfileLogins + x-original-op-title: Logins List + x-linode-cli-command: profile + /profile/logins/{loginId}: + x-akamai: + file-path: paths/profile-login.yaml + path-info: /profile/logins/{loginId} + parameters: + - name: loginId + in: path + description: | + The ID of the login object to access. + example: '{{loginId}}' + x-akamai: + file-path: parameters/login-id-path.yaml + required: true + schema: + type: integer + get: + operationId: get-profile-login + summary: Get a profile's login + tags: + - Logins + description: |- + Returns a login object displaying information about a successful account login from this user. + + + --- + + + - __CLI__. + + ``` + linode-cli profile login-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile login-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested login object. + content: + application/json: + schema: + type: object + description: | + An object representing a previous successful login for a User. + x-akamai: + file-path: schemas/login.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this login object. + example: 1234 + readOnly: true + x-linode-cli-display: 1 + datetime: + type: string + description: | + __Read-only__ When the login was initiated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 2 + ip: + type: string + description: | + __Read-only__ The remote IP address that requested the login. + example: 192.0.2.0 + readOnly: true + format: ip + x-linode-cli-display: 3 + restricted: + type: boolean + description: | + __Read-only__ True if the User that attempted the login was a restricted User, + false otherwise. + example: true + readOnly: true + x-linode-cli-display: 6 + status: + type: string + description: | + __Read-only__ Whether the login attempt succeeded or failed. + example: successful + readOnly: true + enum: + - successful + - failed + x-linode-cli-display: 5 + username: + type: string + description: | + __Read-only__ The username of the User that attempted the login. + example: example_user + readOnly: true + x-linode-cli-display: 4 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-profile-login + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: login-view + x-original-op-id: getProfileLogin + x-original-op-title: Login View + x-linode-cli-command: profile + /profile/phone-number: + x-akamai: + file-path: paths/phone-number.yaml + path-info: /profile/phone-number + post: + operationId: post-profile-phone-number + summary: Send a phone number verification code + tags: + - Phone number + 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 operation you are opting in to receive SMS messages. You can opt out of SMS messages by running the [Delete a phone number](https://techdocs.akamai.com/linode-api/reference/delete-profile-phone-number) operation 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 [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli phone sms-code-send + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli phone sms-code-send + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Enter a phone number and country code for verification. + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - iso_code + - phone_number + properties: + iso_code: + type: string + description: | + The two-letter ISO 3166 country code associated with the phone number. + example: '{{iso_code}}' + phone_number: + type: string + description: | + A valid phone number. + example: '{{phone_number}}' + format: phone + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Phone number verification code request successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: sms-code-send + x-linode-grant: read_write + x-original-op-id: postProfilePhoneNumber + x-original-op-title: Phone Number Verification + Code Send + delete: + operationId: delete-profile-phone-number + summary: Delete a phone number + tags: + - Phone number + description: |- + Delete the verified phone number for the User making this request. + + Use this operation to opt out of SMS messages for the requesting User after a phone number has been verified with the [Verify a phone number](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli phone delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli phone delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Phone number deletion request successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-profile-phone-number + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: delete + x-linode-grant: read_write + x-original-op-id: deleteProfilePhoneNumber + x-original-op-title: Phone Number Delete + x-linode-cli-command: phone + /profile/phone-number/verify: + x-akamai: + file-path: paths/verify.yaml + path-info: /profile/phone-number/verify + post: + operationId: post-profile-phone-number-verify + summary: Verify a phone number + tags: + - Phone number + description: |- + Verify a phone number by confirming the one-time code received via SMS message after running the [Send a phone number verification code](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number) operation. + + - 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 operation. + + Once completed, the verified phone number is assigned to the User making the request. To change the verified phone number for a User, first run the [Delete a phone number](https://techdocs.akamai.com/linode-api/reference/delete-profile-phone-number) operation, then begin the verification process again with the [Send a phone number verification code](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli phone verify + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli phone verify + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Enter a phone verification code for confirmation. + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - otp_code + properties: + otp_code: + type: string + description: | + The one-time code received via SMS message after running the [Send a phone number verification + code](https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number) + operation. + example: '{{otp_code}}' + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Phone number verification successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-profile-phone-number-verify + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: verify + x-linode-grant: read_write + x-original-op-id: postProfilePhoneNumberVerify + x-original-op-title: Phone Number Verify + x-linode-cli-command: phone + /profile/preferences: + x-akamai: + file-path: paths/preferences.yaml + path-info: /profile/preferences + get: + operationId: get-user-preferences + summary: Get user preferences + tags: + - Preferences + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile preferences-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile preferences-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-user-preferences + security: + - personalAccessToken: [] + - oauth: + - account:read_only + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/profile/preferences + x-linode-cli-action: preferences-view + x-linode-cli-skip: true + x-linode-grant: read_only + x-original-op-id: getUserPreferences + x-original-op-title: User Preferences View + put: + operationId: put-user-preferences + summary: Update a user's preferences + tags: + - Preferences + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile preferences-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile preferences-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-user-preferences + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: preferences-update + x-linode-cli-skip: true + x-original-op-id: updateUserPreferences + x-original-op-title: User Preferences Update + x-linode-cli-command: profile + /profile/security-questions: + x-akamai: + file-path: paths/security-questions.yaml + path-info: /profile/security-questions + post: + operationId: post-security-questions + summary: Answer security questions + tags: + - Security questions + 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 [Create a two factor secret](https://techdocs.akamai.com/linode-api/reference/post-tfa-enable) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli security-questions answer + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli security-questions answer + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Answer Security Questions + content: + application/json: + schema: + type: object + description: | + Security questions and responses object for POST operation. + x-akamai: + file-path: schemas/security-questions-post.yaml + additionalProperties: false + properties: + security_questions: + type: array + description: | + Security questions and response objects. + items: + type: object + description: | + Single security question and response object for POST operation. + additionalProperties: false + properties: + question_id: + type: integer + description: | + The ID representing the security question. + example: 1 + response: + type: string + description: | + The security question response. + example: Gotham City + minLength: 3 + maxLength: 17 + security_question: + type: string + description: | + __Read-only__ The security question. + example: In what city were you born? + readOnly: true + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Security Questions answered successfully. + content: + application/json: + schema: + type: object + description: | + Security questions and responses object for POST operation. + x-akamai: + file-path: schemas/security-questions-post.yaml + additionalProperties: false + properties: + security_questions: + type: array + description: | + Security questions and response objects. + items: + type: object + description: | + Single security question and response object for POST operation. + additionalProperties: false + properties: + question_id: + type: integer + description: | + The ID representing the security question. + example: 1 + response: + type: string + description: | + The security question response. + example: Gotham City + minLength: 3 + maxLength: 17 + security_question: + type: string + description: | + __Read-only__ The security question. + example: In what city were you born? + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-security-questions + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: answer + x-linode-cli-skip: true + x-original-op-id: postSecurityQuestions + x-original-op-title: Security Questions Answer + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-security-questions + summary: List security questions + tags: + - Security questions + description: |- + Returns a collection of security questions and their responses, if any, for your User Profile. + + + --- + + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a list of security questions. + content: + application/json: + schema: + type: object + description: | + Security questions and responses object for GET operation. + x-akamai: + file-path: schemas/security-questions-get.yaml + additionalProperties: false + properties: + security_questions: + type: array + description: | + Security questions and response objects. + items: + type: object + description: | + Single security question and response object for GET operation. + additionalProperties: false + properties: + id: + type: integer + description: | + The ID representing the security question. + example: 1 + question: + type: string + description: | + __Read-only__ The security question. + example: In what city were you born? + readOnly: true + response: + type: string + description: | + The security question response. + example: Gotham City + minLength: 3 + maxLength: 17 + x-example: + x-ref: ../examples/tbd.json + x-linode-cli-nested-list: security_questions + x-linode-cli-use-schema: + type: object + additionalProperties: false + 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 + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-security-questions + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: + - list + - ls + x-linode-grant: read_only + x-original-op-id: getSecurityQuestions + x-original-op-title: Security Questions List + x-linode-cli-command: security-questions + /profile/sshkeys: + x-akamai: + file-path: paths/profile-ssh-keys.yaml + path-info: /profile/sshkeys + post: + operationId: post-add-ssh-key + summary: Add an SSH key + tags: + - SSH keys + description: |- + Adds an SSH Key to your Account profile. + + + --- + + + - __CLI__. + + ``` + linode-cli sshkeys create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli sshkeys create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Add SSH Key + content: + application/json: + schema: + type: object + description: | + A credential object for authenticating a User's secure shell connection to a Linode. + x-akamai: + file-path: schemas/ssh-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique identifier of an SSH Key object. + example: '{{id}}' + readOnly: true + created: + type: string + description: | + __Read-only__ The date this key was added. + example: '{{created}}' + readOnly: true + format: date-time + label: + type: string + description: | + A label for the SSH Key. + example: '{{label}}' + minLength: 0 + maxLength: 64 + ssh_key: + type: string + description: |- + The public SSH Key, which is used to authenticate to the root user of the Linodes you deploy. + + Accepted formats: + + - ssh-dss + - ssh-rsa + - ecdsa-sha2-nistp + - ssh-ed25519 + - sk-ecdsa-sha2-nistp256 (Akamai-specific) + example: '{{ssh_key}}' + format: ssh-key + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + SSH Key associated successfully. + content: + application/json: + schema: + type: object + description: | + A credential object for authenticating a User's secure shell connection to a Linode. + x-akamai: + file-path: schemas/ssh-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique identifier of an SSH Key object. + example: 42 + readOnly: true + created: + type: string + description: | + __Read-only__ The date this key was added. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + label: + type: string + description: | + A label for the SSH Key. + example: My SSH Key + minLength: 0 + maxLength: 64 + ssh_key: + type: string + description: |- + The public SSH Key, which is used to authenticate to the root user of the Linodes you deploy. + + Accepted formats: + + - ssh-dss + - ssh-rsa + - ecdsa-sha2-nistp + - ssh-ed25519 + - sk-ecdsa-sha2-nistp256 (Akamai-specific) + example: ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer + format: ssh-key + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-add-ssh-key + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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" + x-linode-cli-action: create + x-original-op-id: addSSHKey + x-original-op-title: SSH Key Add + get: + operationId: get-ssh-keys + summary: List SSH keys + tags: + - SSH keys + description: |- + Returns a collection of SSH Keys you've added to your Profile. + + + --- + + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of SSH Key objects. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A credential object for authenticating a User's secure shell connection to a Linode. + x-akamai: + file-path: schemas/ssh-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique identifier of an SSH Key object. + example: 42 + readOnly: true + created: + type: string + description: | + __Read-only__ The date this key was added. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + label: + type: string + description: | + A label for the SSH Key. + example: My SSH Key + minLength: 0 + maxLength: 64 + ssh_key: + type: string + description: |- + The public SSH Key, which is used to authenticate to the root user of the Linodes you deploy. + + Accepted formats: + + - ssh-dss + - ssh-rsa + - ecdsa-sha2-nistp + - ssh-ed25519 + - sk-ecdsa-sha2-nistp256 (Akamai-specific) + example: ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer + format: ssh-key + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-ssh-keys + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: + - list + - ls + x-linode-grant: read_only + x-original-op-id: getSSHKeys + x-original-op-title: SSH Keys List + x-linode-cli-command: sshkeys + /profile/sshkeys/{sshKeyId}: + x-akamai: + file-path: paths/profile-ssh-key.yaml + path-info: /profile/sshkeys/{sshKeyId} + parameters: + - name: sshKeyId + in: path + description: | + The ID of the SSHKey + example: '{{sshKeyId}}' + x-akamai: + file-path: parameters/ssh-key-id-path.yaml + required: true + schema: + type: integer + get: + operationId: get-ssh-key + summary: Get an SSH key + tags: + - SSH keys + description: |- + Returns a single SSH Key object identified by `id` that you have access to view. + + + --- + + + - __CLI__. + + ``` + linode-cli sshkeys view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli sshkeys view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + An SSH Key object + content: + application/json: + schema: + type: object + description: | + A credential object for authenticating a User's secure shell connection to a Linode. + x-akamai: + file-path: schemas/ssh-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique identifier of an SSH Key object. + example: 42 + readOnly: true + created: + type: string + description: | + __Read-only__ The date this key was added. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + label: + type: string + description: | + A label for the SSH Key. + example: My SSH Key + minLength: 0 + maxLength: 64 + ssh_key: + type: string + description: |- + The public SSH Key, which is used to authenticate to the root user of the Linodes you deploy. + + Accepted formats: + + - ssh-dss + - ssh-rsa + - ecdsa-sha2-nistp + - ssh-ed25519 + - sk-ecdsa-sha2-nistp256 (Akamai-specific) + example: ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer + format: ssh-key + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-ssh-key + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: view + x-original-op-id: getSSHKey + x-original-op-title: SSH Key View + put: + operationId: put-ssh-key + summary: Update an SSH key + tags: + - SSH keys + description: |- + Updates an SSH Key that you have permission to `read_write`. + + Only SSH key labels can be updated. + + + --- + + + - __CLI__. + + ``` + linode-cli sshkeys update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli sshkeys update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The fields to update. + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + label: + type: string + description: | + A label for the SSH Key. + example: '{{label}}' + minLength: 0 + maxLength: 64 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + SSH Key updated successfully. + content: + application/json: + schema: + type: object + description: | + A credential object for authenticating a User's secure shell connection to a Linode. + x-akamai: + file-path: schemas/ssh-key.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique identifier of an SSH Key object. + example: 42 + readOnly: true + created: + type: string + description: | + __Read-only__ The date this key was added. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + label: + type: string + description: | + A label for the SSH Key. + example: My SSH Key + minLength: 0 + maxLength: 64 + ssh_key: + type: string + description: |- + The public SSH Key, which is used to authenticate to the root user of the Linodes you deploy. + + Accepted formats: + + - ssh-dss + - ssh-rsa + - ecdsa-sha2-nistp + - ssh-ed25519 + - sk-ecdsa-sha2-nistp256 (Akamai-specific) + example: ssh-rsa AAAA_valid_public_ssh_key_123456785== user@their-computer + format: ssh-key + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-ssh-key + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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" + x-linode-cli-action: update + x-original-op-id: updateSSHKey + x-original-op-title: SSH Key Update + delete: + operationId: delete-ssh-key + summary: Delete an SSH key + tags: + - SSH keys + 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 operation will only delete the key's association from your Profile. + + + --- + + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + SSH Key deleted successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-ssh-key + security: + - personalAccessToken: [] + - oauth: + - account:read_write + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + -X DELETE \ + https://api.linode.com/v4/profile/sshkeys/42 + - lang: CLI + source: linode-cli sshkeys delete 42 + x-linode-cli-action: + - delete + - rm + x-original-op-id: deleteSSHKey + x-original-op-title: SSH Key Delete + x-linode-cli-command: sshkeys + /profile/tfa-disable: + x-akamai: + file-path: paths/tfa-disable.yaml + path-info: /profile/tfa-disable + post: + operationId: post-tfa-disable + summary: Disable two factor authentication + tags: + - Two factor authentication + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile tfa-disable + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile tfa-disable + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + TFA disabled. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-tfa-disable + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: tfa-disable + x-original-op-id: tfaDisable + x-original-op-title: Two Factor Authentication + Disable + x-linode-cli-command: profile + /profile/tfa-enable: + x-akamai: + file-path: paths/tfa-enable.yaml + path-info: /profile/tfa-enable + post: + operationId: post-tfa-enable + summary: Create a two factor secret + tags: + - Two factor authentication + description: |- + Generates a Two Factor secret for your User. To enable TFA for your User, enter the secret obtained from this operation with the [Enable two factor authentication](https://techdocs.akamai.com/linode-api/reference/post-tfa-confirm) operation. Once enabled, logins from untrusted computers are required to provide a TFA code before they are successful. + + Run the [Answer security questions](https://techdocs.akamai.com/linode-api/reference/post-security-questions) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli profile tfa-enable + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile tfa-enable + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Two Factor secret generated + content: + application/json: + schema: + additionalProperties: false + properties: + expiry: + type: string + description: | + When this Two Factor secret expires. + example: '2018-03-01T00:01:01.000Z' + format: date-time + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-tfa-enable + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: tfa-enable + x-original-op-id: tfaEnable + x-original-op-title: Two Factor Secret Create + x-linode-cli-command: profile + /profile/tfa-enable-confirm: + x-akamai: + file-path: paths/tfa-enable-confirm.yaml + path-info: /profile/tfa-enable-confirm + post: + operationId: post-tfa-confirm + summary: Enable two factor authentication + tags: + - Two factor authentication + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile tfa-confirm + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile tfa-confirm + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The Two Factor code you generated with your Two Factor secret. + required: true + content: + application/json: + schema: + additionalProperties: false + 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' + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + TFA enabled successfully + content: + application/json: + schema: + additionalProperties: false + 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 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-tfa-confirm + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: tfa-confirm + x-original-op-id: tfaConfirm + x-original-op-title: Two Factor Authentication + Confirm/Enable + x-linode-cli-command: profile + /profile/tokens: + x-akamai: + file-path: paths/profile-tokens.yaml + path-info: /profile/tokens + post: + operationId: post-personal-access-token + summary: Create a personal access token + tags: + - Personal access tokens + 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](https://www.linode.com/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 with the [Create a proxy user token](https://techdocs.akamai.com/linode-api/reference/post-child-account-token) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli profile token-create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile token-create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Information about the requested token. + required: true + content: + application/json: + schema: + additionalProperties: false + properties: + expiry: + type: string + description: | + When this token should be valid until. If omitted, the new token will be valid until + it is manually revoked. + example: null + format: date-time + label: + type: string + description: | + This token's label. This is for display purposes only, but can be used to more easily track + what you're using each token for. + example: linode-cli + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: |- + The access [scopes](https://techdocs.akamai.com/linode-api/reference/oauth) 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: '*' + format: oauth-scope + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Token created successfully. + content: + application/json: + schema: + type: object + description: | + A Personal Access Token is a token generated manually to access the API without going through + an OAuth login. Personal Access Tokens can have scopes just like + OAuth tokens do, and are commonly used to give access to command-line + tools like the Linode CLI, or when writing your own integrations. + x-akamai: + file-path: schemas/personal-access-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This token's unique ID, which can be used to revoke it. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token will expire. Personal Access Tokens cannot be renewed, + so after this time the token will be completely unusable and + a new token will need to be generated. Tokens may be created + with "null" as their expiry and will never expire unless revoked. + example: '2018-01-01T13:46:32' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + This token's label. This is for display purposes only, but can be used to more easily + track what you're using each token for. + example: linode-cli + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The scopes this token was created with. These define what parts of the + Account the token can be used to access. Many command-line tools, + such as the [Linode CLI](https://github.com/linode/linode-cli), + require tokens with access to `*`. Tokens with more restrictive + scopes are generally more secure. + example: '*' + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + token: + type: string + description: | + __Read-only__ The token used to access the API. When the token is created, the full + token is returned here. Otherwise, only the first 16 characters + are returned. + example: abcdefghijklmnop + readOnly: true + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-personal-access-token + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: token-create + x-original-op-id: createPersonalAccessToken + x-original-op-title: Personal Access Token Create + get: + operationId: get-personal-access-tokens + summary: List personal access tokens + tags: + - Personal access tokens + description: |- + Returns a paginated list of Personal Access Tokens currently active for your User. + + + --- + + + - __CLI__. + + ``` + linode-cli profile tokens-list + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile tokens-list + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of active tokens. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A Personal Access Token is a token generated manually to access the API without + going through an OAuth login. Personal Access Tokens can + have scopes just like OAuth tokens do, and are commonly used + to give access to command-line tools like the Linode CLI, + or when writing your own integrations. + x-akamai: + file-path: schemas/personal-access-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This token's unique ID, which can be used to revoke it. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token will expire. Personal Access Tokens cannot + be renewed, so after this time the token will be completely + unusable and a new token will need to be generated. Tokens + may be created with "null" as their expiry and will never + expire unless revoked. + example: '2018-01-01T13:46:32' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + This token's label. This is for display purposes only, but can be + used to more easily track what you're using each token + for. + example: linode-cli + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The scopes this token was created with. These define what + parts of the Account the token can be used to access. + Many command-line tools, such as the [Linode CLI](https://github.com/linode/linode-cli), + require tokens with access to `*`. Tokens with more restrictive + scopes are generally more secure. + example: '*' + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + token: + type: string + description: | + __Read-only__ The token used to access the API. When the token is created, + the full token is returned here. Otherwise, only the + first 16 characters are returned. + example: abcdefghijklmnop + readOnly: true + x-linode-cli-display: 5 + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-personal-access-tokens + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: tokens-list + x-original-op-id: getPersonalAccessTokens + x-original-op-title: Personal Access Tokens List + x-linode-cli-command: profile + /profile/tokens/{tokenId}: + x-akamai: + file-path: paths/profile-token.yaml + path-info: /profile/tokens/{tokenId} + parameters: + - name: tokenId + in: path + description: | + The ID of the token to access. + example: '{{tokenId}}' + x-akamai: + file-path: parameters/token-id-path.yaml + required: true + schema: + type: integer + get: + operationId: get-personal-access-token + summary: Get a personal access token + tags: + - Personal access tokens + description: |- + Returns a single Personal Access Token. + + + --- + + + - __CLI__. + + ``` + linode-cli profile token-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile token-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The requested token. + content: + application/json: + schema: + type: object + description: | + A Personal Access Token is a token generated manually to access the API without going through + an OAuth login. Personal Access Tokens can have scopes just like + OAuth tokens do, and are commonly used to give access to command-line + tools like the Linode CLI, or when writing your own integrations. + x-akamai: + file-path: schemas/personal-access-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This token's unique ID, which can be used to revoke it. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token will expire. Personal Access Tokens cannot be renewed, + so after this time the token will be completely unusable and + a new token will need to be generated. Tokens may be created + with "null" as their expiry and will never expire unless revoked. + example: '2018-01-01T13:46:32' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + This token's label. This is for display purposes only, but can be used to more easily + track what you're using each token for. + example: linode-cli + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The scopes this token was created with. These define what parts of the + Account the token can be used to access. Many command-line tools, + such as the [Linode CLI](https://github.com/linode/linode-cli), + require tokens with access to `*`. Tokens with more restrictive + scopes are generally more secure. + example: '*' + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + token: + type: string + description: | + __Read-only__ The token used to access the API. When the token is created, the full + token is returned here. Otherwise, only the first 16 characters + are returned. + example: abcdefghijklmnop + readOnly: true + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-personal-access-token + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: token-view + x-original-op-id: getPersonalAccessToken + x-original-op-title: Personal Access Token View + put: + operationId: put-personal-access-token + summary: Update a personal access token + tags: + - Personal access tokens + description: |- + Updates a Personal Access Token. + + + --- + + + - __CLI__. + + ``` + linode-cli profile token-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile token-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The fields to update. + required: true + content: + application/json: + schema: + type: object + description: | + A Personal Access Token is a token generated manually to access the API without going through + an OAuth login. Personal Access Tokens can have scopes just like + OAuth tokens do, and are commonly used to give access to command-line + tools like the Linode CLI, or when writing your own integrations. + x-akamai: + file-path: schemas/personal-access-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This token's unique ID, which can be used to revoke it. + example: '{{id}}' + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '{{created}}' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token will expire. Personal Access Tokens cannot be renewed, + so after this time the token will be completely unusable and a + new token will need to be generated. Tokens may be created with + "null" as their expiry and will never expire unless revoked. + example: '{{expiry}}' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + This token's label. This is for display purposes only, but can be used to more easily track + what you're using each token for. + example: '{{label}}' + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The scopes this token was created with. These define what parts of the Account + the token can be used to access. Many command-line tools, such + as the [Linode CLI](https://github.com/linode/linode-cli), require + tokens with access to `*`. Tokens with more restrictive scopes + are generally more secure. + example: '{{scopes}}' + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + token: + type: string + description: | + __Read-only__ The token used to access the API. When the token is created, the full token + is returned here. Otherwise, only the first 16 characters are + returned. + example: '{{token}}' + readOnly: true + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Token updated successfully. + content: + application/json: + schema: + type: object + description: | + A Personal Access Token is a token generated manually to access the API without going through + an OAuth login. Personal Access Tokens can have scopes just like + OAuth tokens do, and are commonly used to give access to command-line + tools like the Linode CLI, or when writing your own integrations. + x-akamai: + file-path: schemas/personal-access-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This token's unique ID, which can be used to revoke it. + example: 123 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token will expire. Personal Access Tokens cannot be renewed, + so after this time the token will be completely unusable and + a new token will need to be generated. Tokens may be created + with "null" as their expiry and will never expire unless revoked. + example: '2018-01-01T13:46:32' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + This token's label. This is for display purposes only, but can be used to more easily + track what you're using each token for. + example: linode-cli + minLength: 1 + maxLength: 100 + x-linode-cli-display: 2 + x-linode-filterable: true + scopes: + type: string + description: | + __Read-only__ The scopes this token was created with. These define what parts of the + Account the token can be used to access. Many command-line tools, + such as the [Linode CLI](https://github.com/linode/linode-cli), + require tokens with access to `*`. Tokens with more restrictive + scopes are generally more secure. + example: '*' + readOnly: true + format: oauth-scopes + x-linode-cli-display: 3 + token: + type: string + description: | + __Read-only__ The token used to access the API. When the token is created, the full + token is returned here. Otherwise, only the first 16 characters + are returned. + example: abcdefghijklmnop + readOnly: true + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-personal-access-token + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: token-update + x-original-op-id: updatePersonalAccessToken + x-original-op-title: Personal Access Token Update + delete: + operationId: delete-personal-access-token + summary: Revoke a personal access token + tags: + - Personal access tokens + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli profile token-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli profile token-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Token revoked successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-personal-access-token + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: token-delete + x-original-op-id: deletePersonalAccessToken + x-original-op-title: Personal Access Token Revoke + x-linode-cli-command: profile + /regions: + x-akamai: + file-path: paths/regions.yaml + path-info: /regions + get: + operationId: get-regions + summary: List regions + tags: + - Regions + description: | + Lists the Regions available for Linode services. Not all services are guaranteed to be available in all Regions. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns an array of Regions. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An area where Linode services are available. + x-akamai: + file-path: schemas/region.yaml + additionalProperties: false + properties: + id: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 1 + capabilities: + type: array + description: | + __Read-only__ A list of capabilities of this region. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + - Placement Groups + readOnly: true + items: + type: string + x-linode-cli-display: 4 + country: + type: string + description: | + __Read-only__ The country where this Region resides. + example: us + readOnly: true + x-linode-cli-display: 3 + label: + type: string + description: | + __Read-only__ Detailed location information for this Region, including + city, state or region, and country. + example: Newark, NJ, USA + readOnly: true + x-linode-cli-display: 2 + placement_group_limits: + type: object + description: | + __Read-only__ The limits for [placement groups](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/) + in this region. + additionalProperties: false + readOnly: true + properties: + maximum_linodes_per_pg: + type: integer + description: | + __Read-only__ The maximum number of compute instances you can include + in a single placement group in this region. + example: 5 + readOnly: true + maximum_pgs_per_customer: + type: integer + description: | + __Read-only__ The maximum number of placement groups you can have + in this region. Displayed as `null` if you don't have + a limit. + example: 10 + nullable: true + readOnly: true + x-linode-cli-display: 7 + resolvers: + type: object + additionalProperties: false + readOnly: true + properties: + ipv4: + type: string + description: | + __Read-only__ The IPv4 addresses for this region's DNS resolvers, + separated by commas. + example: 192.0.2.0,192.0.2.1 + readOnly: true + ipv6: + type: string + description: | + __Read-only__ The IPv6 addresses for this region's DNS resolvers, + separated by commas. + example: 2001:0db8::,2001:0db8::1 + readOnly: true + x-linode-cli-display: 6 + status: + type: string + description: | + __Read-only__ This region's current operational status. + example: ok + readOnly: true + enum: + - ok + - outage + x-linode-cli-display: 5 + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-regions + x-code-samples: + - lang: Shell + source: curl https://api.linode.com/v4/regions + - lang: CLI + source: linode-cli regions list + x-linode-cli-action: + - list + - ls + x-linode-redoc-load-ids: true + x-original-op-id: getRegions + x-original-op-title: Regions List + x-linode-cli-command: regions + /regions/availability: + x-akamai: + file-path: paths/regions-availability.yaml + path-info: /regions/availability + get: + operationId: get-regions-availability + summary: List regions' availability + tags: + - Regions + description: |- + Returns availability data for all Regions. + + Currently, this operation returns availability of select premium and GPU plans for select regions. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a Region Availability object. + content: + application/json: + schema: + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - properties: + data: + type: array + items: + type: object + description: | + Compute instance availability information by [Type](https://techdocs.akamai.com/linode-api/reference/get-linode-types) + and [Region](https://techdocs.akamai.com/linode-api/reference/get-regions). + x-akamai: + file-path: schemas/region-availability.yaml + additionalProperties: false + properties: + available: + type: boolean + description: | + Whether the compute instance type is available in the region. + example: true + x-linode-cli-display: 3 + x-linode-filterable: true + plan: + type: string + description: | + The compute instance [Type](https://techdocs.akamai.com/linode-api/reference/get-linode-types) + ID. + example: gpu-rtx6000-1.1 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The [Region](https://techdocs.akamai.com/linode-api/reference/get-regions) ID. + example: us-east + x-linode-cli-display: 1 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-regions-availability + x-code-samples: + - lang: Shell + source: curl https://api.linode.com/v4/regions/availability + - lang: CLI + source: linode-cli regions list-avail + x-linode-cli-action: list-avail + x-original-op-id: getRegionsAvailability + x-original-op-title: Regions Availability List + x-linode-cli-command: regions + /regions/{regionId}: + x-akamai: + file-path: paths/region.yaml + path-info: /regions/{regionId} + parameters: + - name: regionId + in: path + description: | + ID of the Region to look up. + example: '{{regionId}}' + x-akamai: + file-path: parameters/region-id-path.yaml + required: true + schema: + type: string + get: + operationId: get-region + summary: Get a region + tags: + - Regions + description: | + Returns a single Region. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A single Region object. + content: + application/json: + schema: + type: object + description: | + An area where Linode services are available. + x-akamai: + file-path: schemas/region.yaml + additionalProperties: false + properties: + id: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 1 + capabilities: + type: array + description: | + __Read-only__ A list of capabilities of this region. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + - Placement Groups + readOnly: true + items: + type: string + x-linode-cli-display: 4 + country: + type: string + description: | + __Read-only__ The country where this Region resides. + example: us + readOnly: true + x-linode-cli-display: 3 + label: + type: string + description: | + __Read-only__ Detailed location information for this Region, including city, state + or region, and country. + example: Newark, NJ, USA + readOnly: true + x-linode-cli-display: 2 + placement_group_limits: + type: object + description: | + __Read-only__ The limits for [placement groups](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/) + in this region. + additionalProperties: false + readOnly: true + properties: + maximum_linodes_per_pg: + type: integer + description: | + __Read-only__ The maximum number of compute instances you can include in a + single placement group in this region. + example: 5 + readOnly: true + maximum_pgs_per_customer: + type: integer + description: | + __Read-only__ The maximum number of placement groups you can have in this + region. Displayed as `null` if you don't have a limit. + example: 10 + nullable: true + readOnly: true + x-linode-cli-display: 7 + resolvers: + type: object + additionalProperties: false + readOnly: true + properties: + ipv4: + type: string + description: | + __Read-only__ The IPv4 addresses for this region's DNS resolvers, separated + by commas. + example: 192.0.2.0,192.0.2.1 + readOnly: true + ipv6: + type: string + description: | + __Read-only__ The IPv6 addresses for this region's DNS resolvers, separated + by commas. + example: 2001:0db8::,2001:0db8::1 + readOnly: true + x-linode-cli-display: 6 + status: + type: string + description: | + __Read-only__ This region's current operational status. + example: ok + readOnly: true + enum: + - ok + - outage + x-linode-cli-display: 5 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-region + x-code-samples: + - lang: Shell + source: curl https://api.linode.com/v4/regions/us-east + - lang: CLI + source: linode-cli regions view us-east + x-linode-cli-action: view + x-original-op-id: getRegion + x-original-op-title: Region View + x-linode-cli-command: regions + /regions/{regionId}/availability: + x-akamai: + file-path: paths/region-availability.yaml + path-info: /regions/{regionId}/availability + parameters: + - name: regionId + in: path + description: | + ID of the Region to look up. + example: '{{regionId}}' + x-akamai: + file-path: parameters/region-id-path.yaml + required: true + schema: + type: string + get: + operationId: get-region-availability + summary: Get a region's availability + tags: + - Regions + description: | + Returns availability data for a single Region. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The availability data for a single Region. + content: + application/json: + schema: + type: array + items: + type: object + description: | + Compute instance availability information by [Type](https://techdocs.akamai.com/linode-api/reference/get-linode-types) + and [Region](https://techdocs.akamai.com/linode-api/reference/get-regions). + x-akamai: + file-path: schemas/region-availability.yaml + additionalProperties: false + properties: + available: + type: boolean + description: | + Whether the compute instance type is available in the region. + example: true + x-linode-cli-display: 3 + x-linode-filterable: true + plan: + type: string + description: | + The compute instance [Type](https://techdocs.akamai.com/linode-api/reference/get-linode-types) + ID. + example: gpu-rtx6000-1.1 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The [Region](https://techdocs.akamai.com/linode-api/reference/get-regions) ID. + example: us-east + x-linode-cli-display: 1 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-region-availability + 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 + x-linode-cli-action: view-avail + x-original-op-id: getRegionAvailability + x-original-op-title: Region Availability View + x-linode-cli-command: regions + /support/tickets: + x-akamai: + file-path: paths/tickets.yaml + path-info: /support/tickets + post: + operationId: post-ticket + summary: Open a support ticket + tags: + - Support tickets + description: |- + Open a Support Ticket. Only one of the ID attributes (`linode_id`, `domain_id`, etc.) can be set on a single Support Ticket. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Open a Support Ticket. + content: + application/json: + schema: + type: object + description: | + An object representing a created Support Ticket - a question or issue and request for help + from the Linode support team. Only one of the ID attributes (`linode_id`, + `domain_id`, etc.) can be set on a single Support Ticket. + x-akamai: + file-path: schemas/support-ticket-request.yaml + additionalProperties: false + required: + - summary + - description + properties: + summary: + type: string + description: | + The summary or title for this SupportTicket. + example: '{{summary}}' + minLength: 1 + maxLength: 64 + description: + type: string + description: | + The full details of the issue or question. + example: '{{description}}' + minLength: 1 + maxLength: 65000 + database_id: + type: integer + description: | + The ID of the Managed Database this ticket is regarding, if relevant. + example: '{{database_id}}' + domain_id: + type: integer + description: | + The ID of the Domain this ticket is regarding, if relevant. + example: '{{domain_id}}' + firewall_id: + type: integer + description: | + The ID of the Firewall this ticket is regarding, if relevant. + example: '{{firewall_id}}' + linode_id: + type: integer + description: | + The ID of the Linode this ticket is regarding, if relevant. + example: '{{linode_id}}' + lkecluster_id: + type: integer + description: | + The ID of the Kubernetes cluster this ticket is regarding, if relevant. + example: '{{lkecluster_id}}' + longviewclient_id: + type: integer + description: | + The ID of the Longview client this ticket is regarding, if relevant. + example: '{{longviewclient_id}}' + managed_issue: + type: boolean + description: |- + Designates if this ticket is related to a [Managed service](https://www.linode.com/products/managed/). If `true`, the following constraints will apply: + + - No ID attributes (i.e. `linode_id`, `domain_id`, etc.) should be provided with this request. + - Your account must have a managed service [enabled](https://techdocs.akamai.com/linode-api/reference/post-enable-managed-service). + example: '{{managed_issue}}' + nodebalancer_id: + type: integer + description: | + The ID of the NodeBalancer this ticket is regarding, if relevant. + example: '{{nodebalancer_id}}' + region: + type: string + description: |- + The [Region](https://techdocs.akamai.com/linode-api/reference/get-regions) ID for the associated VLAN this ticket is regarding. + + Only allowed when submitting a VLAN ticket. + example: '{{region}}' + vlan: + type: string + description: |- + The label of the VLAN this ticket is regarding, if relevant. To view your VLANs, run the [List VLANs](https://techdocs.akamai.com/linode-api/reference/get-vlans)) operation. + + Requires a specified `region` to identify the VLAN. + example: '{{vlan}}' + volume_id: + type: integer + description: | + The ID of the Volume this ticket is regarding, if relevant. + example: '{{volume_id}}' + vpc_id: + type: integer + description: | + The ID of the VPC this ticket is regarding, if relevant. + example: '{{vpc_id}}' + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Support Ticket opened. + content: + application/json: + schema: + type: object + description: | + A Support Ticket opened on your Account. + x-akamai: + file-path: schemas/support-ticket.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The ID of the Support Ticket. + example: 11223344 + readOnly: true + x-linode-cli-display: 1 + summary: + type: string + description: | + __Read-only__ The summary or title for this Ticket. + example: Having trouble resetting root password on my Linode + readOnly: true + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + description: + type: string + description: | + __Read-only__ The full details of the issue or question. + example: I am having trouble setting the root password on my Linode. I tried following the instructions + but something is not working. Can you please help me figure + out how I can reset it? + readOnly: true + minLength: 1 + maxLength: 65000 + x-linode-cli-display: 5 + attachments: + type: array + description: | + __Read-only__ A list of filenames representing attached files associated with this + Ticket. + readOnly: true + items: + type: string + example: + - screenshot.jpg + - screenshot.txt + closable: + type: boolean + description: | + Whether the Support Ticket may be closed. + example: false + closed: + type: string + description: | + __Read-only__ The date and time this Ticket was closed. + example: '2015-06-04T16:07:03' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + entity: + type: object + description: | + __Read-only__ The entity this Ticket was opened for. + additionalProperties: false + nullable: true + readOnly: true + properties: + id: + type: integer + description: | + __Read-only__ The unique ID for this Ticket's entity. + example: 10400 + readOnly: true + type: + type: string + description: | + __Read-only__ The type of entity this is related to. + example: linode + readOnly: true + label: + type: string + description: | + __Read-only__ The current label of this entity. + example: linode123456 + readOnly: true + url: + type: string + description: | + __Read-only__ The URL where you can access the object this event is for. If + a relative URL, it is relative to the domain you retrieved + the entity from. + example: /v4/linode/instances/123456 + readOnly: true + x-linode-cli-display: 6 + gravatar_id: + type: string + description: | + __Read-only__ The Gravatar ID of the User who opened this Ticket. + example: 474a1b7373ae0be4132649e69c36ce30 + readOnly: true + opened: + type: string + description: | + __Read-only__ The date and time this Ticket was created. + example: '2015-06-04T14:16:44' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + opened_by: + type: string + description: | + __Read-only__ The User who opened this Ticket. + example: some_user + readOnly: true + x-linode-cli-display: 3 + status: + type: string + description: | + __Read-only__ The current status of this Ticket. + example: open + readOnly: true + enum: + - closed + - new + - open + updated: + type: string + description: | + __Read-only__ The date and time this Ticket was last updated. + example: '2015-06-04T16:07:03' + readOnly: true + format: date-time + x-linode-filterable: true + updated_by: + type: string + description: | + __Read-only__ The User who last updated this Ticket. + example: some_other_user + nullable: true + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-ticket + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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" + x-linode-cli-action: create + x-linode-grant: read_write + x-original-op-id: createTicket + x-original-op-title: Support Ticket Open + get: + operationId: get-tickets + summary: List support tickets + tags: + - Support tickets + 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. + + + --- + + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of SupportTicket objects. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A Support Ticket opened on your Account. + x-akamai: + file-path: schemas/support-ticket.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The ID of the Support Ticket. + example: 11223344 + readOnly: true + x-linode-cli-display: 1 + summary: + type: string + description: | + __Read-only__ The summary or title for this Ticket. + example: Having trouble resetting root password on my Linode + readOnly: true + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + description: + type: string + description: | + __Read-only__ The full details of the issue or question. + example: I am having trouble setting the root password on my Linode. I tried following + the instructions but something is not working. Can you + please help me figure out how I can reset it? + readOnly: true + minLength: 1 + maxLength: 65000 + x-linode-cli-display: 5 + attachments: + type: array + description: | + __Read-only__ A list of filenames representing attached files associated + with this Ticket. + readOnly: true + items: + type: string + example: + - screenshot.jpg + - screenshot.txt + closable: + type: boolean + description: | + Whether the Support Ticket may be closed. + example: false + closed: + type: string + description: | + __Read-only__ The date and time this Ticket was closed. + example: '2015-06-04T16:07:03' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + entity: + type: object + description: | + __Read-only__ The entity this Ticket was opened for. + additionalProperties: false + nullable: true + readOnly: true + properties: + id: + type: integer + description: | + __Read-only__ The unique ID for this Ticket's entity. + example: 10400 + readOnly: true + type: + type: string + description: | + __Read-only__ The type of entity this is related to. + example: linode + readOnly: true + label: + type: string + description: | + __Read-only__ The current label of this entity. + example: linode123456 + readOnly: true + url: + type: string + description: | + __Read-only__ The URL where you can access the object this event + is for. If a relative URL, it is relative to the domain + you retrieved the entity from. + example: /v4/linode/instances/123456 + readOnly: true + x-linode-cli-display: 6 + gravatar_id: + type: string + description: | + __Read-only__ The Gravatar ID of the User who opened this Ticket. + example: 474a1b7373ae0be4132649e69c36ce30 + readOnly: true + opened: + type: string + description: | + __Read-only__ The date and time this Ticket was created. + example: '2015-06-04T14:16:44' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + opened_by: + type: string + description: | + __Read-only__ The User who opened this Ticket. + example: some_user + readOnly: true + x-linode-cli-display: 3 + status: + type: string + description: | + __Read-only__ The current status of this Ticket. + example: open + readOnly: true + enum: + - closed + - new + - open + updated: + type: string + description: | + __Read-only__ The date and time this Ticket was last updated. + example: '2015-06-04T16:07:03' + readOnly: true + format: date-time + x-linode-filterable: true + updated_by: + type: string + description: | + __Read-only__ The User who last updated this Ticket. + example: some_other_user + nullable: true + readOnly: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-tickets + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: + - list + - ls + x-linode-grant: read_only + x-original-op-id: getTickets + x-original-op-title: Support Tickets List + x-linode-cli-command: tickets + /support/tickets/{ticketId}: + x-akamai: + file-path: paths/ticket.yaml + path-info: /support/tickets/{ticketId} + parameters: + - name: ticketId + in: path + description: | + The ID of the Support Ticket. + example: '{{ticketId}}' + x-akamai: + file-path: parameters/ticket-id.yaml + required: true + schema: + type: integer + get: + operationId: get-ticket + summary: Get a support ticket + tags: + - Support tickets + description: |- + Returns a Support Ticket under your Account. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a single SupportTicket object. + content: + application/json: + schema: + type: object + description: | + A Support Ticket opened on your Account. + x-akamai: + file-path: schemas/support-ticket.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The ID of the Support Ticket. + example: 11223344 + readOnly: true + x-linode-cli-display: 1 + summary: + type: string + description: | + __Read-only__ The summary or title for this Ticket. + example: Having trouble resetting root password on my Linode + readOnly: true + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + description: + type: string + description: | + __Read-only__ The full details of the issue or question. + example: I am having trouble setting the root password on my Linode. I tried following the instructions + but something is not working. Can you please help me figure + out how I can reset it? + readOnly: true + minLength: 1 + maxLength: 65000 + x-linode-cli-display: 5 + attachments: + type: array + description: | + __Read-only__ A list of filenames representing attached files associated with this + Ticket. + readOnly: true + items: + type: string + example: + - screenshot.jpg + - screenshot.txt + closable: + type: boolean + description: | + Whether the Support Ticket may be closed. + example: false + closed: + type: string + description: | + __Read-only__ The date and time this Ticket was closed. + example: '2015-06-04T16:07:03' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + entity: + type: object + description: | + __Read-only__ The entity this Ticket was opened for. + additionalProperties: false + nullable: true + readOnly: true + properties: + id: + type: integer + description: | + __Read-only__ The unique ID for this Ticket's entity. + example: 10400 + readOnly: true + type: + type: string + description: | + __Read-only__ The type of entity this is related to. + example: linode + readOnly: true + label: + type: string + description: | + __Read-only__ The current label of this entity. + example: linode123456 + readOnly: true + url: + type: string + description: | + __Read-only__ The URL where you can access the object this event is for. If + a relative URL, it is relative to the domain you retrieved + the entity from. + example: /v4/linode/instances/123456 + readOnly: true + x-linode-cli-display: 6 + gravatar_id: + type: string + description: | + __Read-only__ The Gravatar ID of the User who opened this Ticket. + example: 474a1b7373ae0be4132649e69c36ce30 + readOnly: true + opened: + type: string + description: | + __Read-only__ The date and time this Ticket was created. + example: '2015-06-04T14:16:44' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + opened_by: + type: string + description: | + __Read-only__ The User who opened this Ticket. + example: some_user + readOnly: true + x-linode-cli-display: 3 + status: + type: string + description: | + __Read-only__ The current status of this Ticket. + example: open + readOnly: true + enum: + - closed + - new + - open + updated: + type: string + description: | + __Read-only__ The date and time this Ticket was last updated. + example: '2015-06-04T16:07:03' + readOnly: true + format: date-time + x-linode-filterable: true + updated_by: + type: string + description: | + __Read-only__ The User who last updated this Ticket. + example: some_other_user + nullable: true + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-ticket + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: view + x-linode-grant: read_only + x-original-op-id: getTicket + x-original-op-title: Support Ticket View + x-linode-cli-command: tickets + /support/tickets/{ticketId}/attachments: + x-akamai: + file-path: paths/attachments.yaml + path-info: /support/tickets/{ticketId}/attachments + parameters: + - name: ticketId + in: path + description: | + The ID of the Support Ticket. + example: '{{ticketId}}' + x-akamai: + file-path: parameters/ticket-id.yaml + required: true + schema: + type: integer + post: + operationId: post-ticket-attachment + summary: Create a support ticket attachment + tags: + - Attachments + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets upload-attachment + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets upload-attachment + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Add an attachment. + required: true + content: + application/json: {} + multipart/form-data: + schema: + additionalProperties: false + 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 + x-ref: ../schemas/added-tbd.yaml + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Attachment created. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-ticket-attachment + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: upload-attachment + x-linode-cli-skip: true + x-linode-grant: read_write + x-original-op-id: createTicketAttachment + x-original-op-title: Support Ticket Attachment + Create + x-linode-cli-command: tickets + /support/tickets/{ticketId}/close: + x-akamai: + file-path: paths/close.yaml + path-info: /support/tickets/{ticketId}/close + parameters: + - name: ticketId + in: path + description: | + The ID of the Support Ticket. + example: '{{ticketId}}' + x-akamai: + file-path: parameters/ticket-id.yaml + required: true + schema: + type: integer + post: + operationId: post-close-ticket + summary: Close a support ticket + tags: + - Support tickets + description: |- + Closes a Support Ticket you have access to modify. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets close + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets close + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Support Ticket closed successfully. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-close-ticket + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: close + x-linode-grant: read_write + x-original-op-id: closeTicket + x-original-op-title: Support Ticket Close + x-linode-cli-command: tickets + /support/tickets/{ticketId}/replies: + x-akamai: + file-path: paths/replies.yaml + path-info: /support/tickets/{ticketId}/replies + parameters: + - name: ticketId + in: path + description: | + The ID of the Support Ticket. + example: '{{ticketId}}' + x-akamai: + file-path: parameters/ticket-id.yaml + required: true + schema: + type: integer + post: + operationId: post-ticket-reply + summary: Create a reply + tags: + - Replies + description: |- + Adds a reply to an existing Support Ticket. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets reply + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets reply + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Add a reply. + required: true + content: + application/json: + schema: + additionalProperties: false + required: + - description + properties: + description: + type: string + description: | + The content of your reply. + 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! + minLength: 1 + maxLength: 65535 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Reply created. + content: + application/json: + schema: + type: object + description: | + An object representing a reply to a Support Ticket. + x-akamai: + file-path: schemas/support-ticket-reply.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Support Ticket reply. + example: 11223345 + readOnly: true + x-linode-cli-display: 1 + description: + type: string + description: | + __Read-only__ The body of this Support Ticket reply. + example: Hello,\nI'm sorry to hear that you are having trouble resetting the root password of your + Linode. Just to be sure, have you tried to follow the instructions + in our online documentation? The link is here:\n \nhttps://linode.com/docs/guides/reset-the-root-password-on-your-linode/ + \n\nIf you have, please reply with any additional steps you + have also taken.\n\nRegards, Linode Support Team + readOnly: true + created: + type: string + description: | + __Read-only__ The date and time this Ticket reply was created. + example: '2015-06-02T14:31:41' + readOnly: true + format: date-time + x-linode-cli-display: 3 + created_by: + type: string + description: | + __Read-only__ The User who submitted this reply. + example: John Q. Linode + readOnly: true + x-linode-cli-display: 2 + from_linode: + type: boolean + description: | + __Read-only__ If set to true, this reply came from a Linode employee. + example: true + readOnly: true + gravatar_id: + type: string + description: | + __Read-only__ The Gravatar ID of the User who created this reply. + example: 474a1b7373ae0be4132649e69c36ce30 + readOnly: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-ticket-reply + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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!" + x-linode-cli-action: reply + x-linode-grant: read_write + x-original-op-id: createTicketReply + x-original-op-title: Reply Create + get: + operationId: get-ticket-replies + summary: List replies + tags: + - Replies + description: |- + Returns a collection of replies to a Support Ticket on your Account. + + + --- + + + - __CLI__. + + ``` + linode-cli tickets replies + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tickets replies + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of SupportTicketReply objects. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + An object representing a reply to a Support Ticket. + x-akamai: + file-path: schemas/support-ticket-reply.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Support Ticket reply. + example: 11223345 + readOnly: true + x-linode-cli-display: 1 + description: + type: string + description: | + __Read-only__ The body of this Support Ticket reply. + example: Hello,\nI'm sorry to hear that you are having trouble resetting the root + password of your Linode. Just to be sure, have you tried + to follow the instructions in our online documentation? + The link is here:\n \nhttps://linode.com/docs/guides/reset-the-root-password-on-your-linode/ + \n\nIf you have, please reply with any additional steps + you have also taken.\n\nRegards, Linode Support Team + readOnly: true + created: + type: string + description: | + __Read-only__ The date and time this Ticket reply was created. + example: '2015-06-02T14:31:41' + readOnly: true + format: date-time + x-linode-cli-display: 3 + created_by: + type: string + description: | + __Read-only__ The User who submitted this reply. + example: John Q. Linode + readOnly: true + x-linode-cli-display: 2 + from_linode: + type: boolean + description: | + __Read-only__ If set to true, this reply came from a Linode employee. + example: true + readOnly: true + gravatar_id: + type: string + description: | + __Read-only__ The Gravatar ID of the User who created this reply. + example: 474a1b7373ae0be4132649e69c36ce30 + readOnly: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-ticket-replies + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: replies + x-linode-grant: read_only + x-original-op-id: getTicketReplies + x-original-op-title: Replies List + x-linode-cli-command: tickets + /tags: + x-akamai: + file-path: paths/tags.yaml + path-info: /tags + post: + operationId: post-tag + summary: Create a tag + tags: + - Tags + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli tags create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli tags create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The tag to create, and optionally the objects to tag. + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - label + properties: + domains: + type: array + 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 + items: + type: integer + label: + type: string + description: | + The new Tag. + example: '{{label}}' + minLength: 3 + maxLength: 50 + linodes: + type: array + 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 + items: + type: integer + nodebalancers: + type: array + 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 + items: + type: integer + volumes: + type: array + 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 + items: + type: integer + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The new Tag. + content: + application/json: + schema: + type: object + description: | + A tag that has been applied to an object on your Account. Tags are currently for organizational + purposes only. + x-akamai: + file-path: schemas/tag.yaml + additionalProperties: false + properties: + label: + type: string + description: | + A Label used for organization of objects on your Account. + example: example tag + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-tag + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: create + x-linode-grant: unrestricted only + x-original-op-id: createTag + x-original-op-title: New Tag Create + get: + operationId: get-tags + summary: List tags + tags: + - Tags + 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 operation 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. + + + --- + + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of Tags + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A tag that has been applied to an object on your Account. Tags are currently for + organizational purposes only. + x-akamai: + file-path: schemas/tag.yaml + additionalProperties: false + properties: + label: + type: string + description: | + A Label used for organization of objects on your Account. + example: example tag + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-tags + security: + - personalAccessToken: [] + - oauth: + - account:read_only + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/tags + x-linode-cli-action: + - list + - ls + x-linode-grant: unrestricted only + x-original-op-id: getTags + x-original-op-title: Tags List + x-linode-cli-command: tags + /tags/{tagLabel}: + x-akamai: + file-path: paths/tag-label.yaml + path-info: /tags/{tagLabel} + parameters: + - name: tagLabel + in: path + example: '{{tagLabel}}' + x-akamai: + file-path: parameters/tag-label-path.yaml + required: true + schema: + type: string + description: | + The `label` of the Tag to access. + get: + operationId: get-tagged-objects + summary: List tagged objects + tags: + - Tags + 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. + + + --- + + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of objects, organized by type, that have been tagged with the requested Tag. + content: + application/json: + schema: + additionalProperties: false + properties: + data: + type: array + items: + type: object + additionalProperties: false + properties: + type: + type: string + example: linode + data: + discriminator: + propertyName: type + oneOf: + - type: object + x-akamai: + file-path: schemas/linode.yaml + title: Linode + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This Linode's ID which must be provided for all + operations impacting this Linode. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + tags: + type: array + description: | + An array of tags applied to this object. Tags are for organizational + purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + type: + type: string + description: | + __Read-only__ This is the [Linode type](https://techdocs.akamai.com/linode-api/reference/get-linode-types) + that this Linode was deployed with. To change a + Linode's Type, use [Resize a Linode](https://techdocs.akamai.com/linode-api/reference/post-resize-linode-instance). + example: g6-standard-1 + readOnly: true + x-linode-cli-display: 4 + alerts: + type: object + additionalProperties: false + properties: + cpu: + type: integer + description: |- + The percentage of CPU usage required to trigger an alert. If the average CPU usage over two hours exceeds this value, we'll send you an alert. Your Linode's total CPU capacity is represented as 100%, multiplied by its number of cores. + + For example, a two core Linode's CPU capacity is represented as 200%. If you want to be alerted at 90% of a two core Linode's CPU capacity, set the alert value to `180`. + + The default value is 90% multiplied by the number of cores. + + If the value is set to `0` (zero), the alert is disabled. + example: 180 + io: + type: integer + description: | + The amount of disk IO operation per second required + to trigger an alert. If the average disk IO + over two hours exceeds this value, we'll send + you an alert. If set to `0` (zero), this alert + is disabled. + example: 10000 + network_in: + type: integer + description: | + The amount of incoming traffic, in Mbit/s, required + to trigger an alert. If the average incoming + traffic over two hours exceeds this value, we'll + send you an alert. If this is set to `0` (zero), + the alert is disabled. + example: 10 + network_out: + type: integer + description: | + The amount of outbound traffic, in Mbit/s, required + to trigger an alert. If the average outbound + traffic over two hours exceeds this value, we'll + send you an alert. If this is set to `0` (zero), + the alert is disabled. + example: 10 + transfer_quota: + type: integer + description: | + The percentage of network transfer that may be used + before an alert is triggered. When this value + is exceeded, we'll alert you. If this is set + to `0` (zero), the alert is disabled. + example: 80 + backups: + type: object + description: | + Information about this Linode's backups status. For information + about available backups, run [List backups](https://techdocs.akamai.com/linode-api/reference/get-backups). + additionalProperties: false + properties: + available: + type: boolean + description: |- + __Read-only__ Whether Backups for this Linode are available for restoration. + + Backups undergoing maintenance are not available for restoration. + example: true + readOnly: true + enabled: + type: boolean + description: | + __Read-only__ If this Linode has the Backup service enabled. + To enable backups, run [Enable backups](https://techdocs.akamai.com/linode-api/reference/post-enable-backups). + example: true + readOnly: true + last_successful: + type: string + description: | + __Read-only__ The last successful backup date. 'null' if there + was no previous backup. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + schedule: + type: object + additionalProperties: false + properties: + day: + type: string + description: |- + The day of the week that your Linode's weekly Backup is taken. If not set manually, a day will be chosen for you. Backups are taken every day, but backups taken on this day are preferred when selecting backups to retain for a longer period. + + If not set manually, then when backups are initially enabled, this may come back as `Scheduling` until the `day` is automatically selected. + example: Saturday + nullable: true + enum: + - Scheduling + - Sunday + - Monday + - Tuesday + - Wednesday + - Thursday + - Friday + - Saturday + window: + type: string + description: |- + The window in which your backups will be taken, in UTC. A backups window is a two-hour span of time in which the backup may occur. + + For example, `W10` indicates that your backups should be taken between 10:00 and 12:00. If you do not choose a backup window, one will be selected for you automatically. + + If not set manually, when backups are initially enabled this may come back as `Scheduling` until the `window` is automatically selected. + example: W22 + nullable: true + enum: + - Scheduling + - W0 + - W2 + - W4 + - W6 + - W8 + - W10 + - W12 + - W14 + - W16 + - W18 + - W20 + - W22 + created: + type: string + description: | + __Read-only__ When this Linode was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + disk_encryption: + type: string + description: | + Local disk encryption ensures that your data stored on compute + instances is encrypted. Encryption converts the + data on the compute instance into unreadable code. + Decryption of the the disk requires other systems + within the datacenter. This requirement protects + against data leakage if the disk is removed from + a datacenter, lost, stolen, recycled or disposed. + example: enabled + default: enabled + enum: + - enabled + - disabled + group: + type: string + description: | + A deprecated property denoting a group label for this Linode. + example: Linode-Group + deprecated: true + x-linode-filterable: true + has_user_data: + type: boolean + description: | + __Read-only__ Whether this compute instance was provisioned utilizing + `user_data` provided via the Metadata service. See + the [Create a Linode](https://techdocs.akamai.com/linode-api/reference/post-linode-instance) + description for more information on Metadata. + example: true + readOnly: true + host_uuid: + type: string + description: | + __Read-only__ The Linode's host machine, as a UUID. + example: 3a3ddd59d9a78bb8de041391075df44de62bfec8 + readOnly: true + format: uuid + hypervisor: + type: string + description: | + __Read-only__ The virtualization software powering this Linode. + example: kvm + readOnly: true + enum: + - kvm + image: + example: linode/debian10 + nullable: true + readOnly: true + allOf: + - type: string + description: |- + An Image ID to deploy the Linode Disk from. + + Run the [List images](https://techdocs.akamai.com/linode-api/reference/get-images) operation with authentication to view all available Images. Official Linode Images start with `linode/`, while your Account's Images start with `private/`. Creating a disk from a Private Image requires `read_only` or `read_write` permissions for that Image. Run the [Update a user's grants](https://techdocs.akamai.com/linode-api/reference/put-user-grants) operation to adjust permissions for an Account Image. + example: linode/debian9 + x-linode-cli-display: 5 + x-linode-filterable: true + ipv4: + type: array + description: |- + __Read-only__ This Linode's IPv4 Addresses. Each Linode is assigned a single public IPv4 address upon creation, and may get a single private IPv4 address if needed. You may need to [Open a support ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) to get additional IPv4 addresses. + + IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes. See the [networking](https://techdocs.akamai.com/linode-api/reference/post-firewalls) operations for details. + example: + - 203.0.113.1 + - 192.0.2.1 + readOnly: true + format: ipv4 + items: + type: string + x-linode-cli-display: 7 + x-linode-filterable: true + ipv6: + type: string + description: | + __Read-only__ This Linode's IPv6 SLAAC address. This address is + specific to a Linode, and may not be shared. If + the Linode has not been assigned an IPv6 address, + the return value will be `null`. + example: c001:d00d::1337/128 + nullable: true + readOnly: true + format: ipv6/128 + label: + type: string + description: |- + The Linode's label is for display purposes only. If no label is provided for a Linode, a default will be assigned. + + Linode labels have the following constraints: + + - Must begin and end with an alphanumeric character. + - May only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + - Cannot have two hyphens (`--`), underscores (`__`) or periods (`..`) in a row. + example: linode123 + minLength: 3 + maxLength: 64 + pattern: ^[a-zA-Z]((?!--|__|..)[a-zA-Z0-9-_.])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + placement_group: + type: object + description: | + __Read-only__ Details on the [placement group](https://www.linode.com/docs/products/compute/compute-instances/guides/placement-groups/) + that this Linode belongs to. Empty if the Linode + isn't in a placement group. + additionalProperties: false + nullable: true + readOnly: true + properties: + id: + type: integer + description: | + The placement group's ID. You need to provide it + for all operations impacting it. + example: 528 + nullable: false + x-linode-cli-display: 1 + affinity_type: + type: string + description: |- + __Read-only__ How compute instances are distributed in your placement group. `anti-affinity:local` places compute instances in separate fault domains, but still in the same region. + + __Note__: With the limited availability release, only `anti_affinity:local` is available for `affinity_type`. + example: anti-affinity:local + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + is_strict: + type: boolean + description: |- + How the API enforces your `affinity_type`: + + - Set to `true`, your group is strict. You can't add more compute instances to your placement group if your preferred container lacks capacity or is unavailable. + - Set to `false`, your group is flexible. You can add more compute instances to it even if they violate the `affinity_type`. If you violate the `affinity_type` your placement group becomes non-compliant and you need to wait for our assistance. + example: true + nullable: false + label: + type: string + description: |- + The unique name set for the placement group. A label has these constraints: + + - It needs to begin and end with an alphanumeric character. + - It can only consist of alphanumeric characters, hyphens (`-`), underscores (`_`) or periods (`.`). + example: PG_Miami_failover + minLength: 1 + x-linode-cli-display: 1 + x-linode-filterable: true + region: + type: string + description: | + __Read-only__ This is the [region](https://techdocs.akamai.com/linode-api/reference/get-regions) + where the Linode was deployed. A Linode's region + can only be changed by initiating a [cross data + center migration](https://techdocs.akamai.com/linode-api/reference/post-migrate-linode-instance). + example: us-east + readOnly: true + x-linode-cli-display: 3 + x-linode-filterable: true + specs: + type: object + description: | + __Read-only__ Information about the resources available to this + Linode. + additionalProperties: false + readOnly: true + properties: + disk: + type: integer + description: | + __Read-only__ The amount of storage space, in MB, this Linode + has access to. A typical Linode will divide + this space between a primary disk with an `image` + deployed to it, and a swap disk, usually 512 + MB. This is the default configuration created + when deploying a Linode with an `image` through + [Create a Linode](https://techdocs.akamai.com/linode-api/reference/post-linode-instance). + While this configuration is suitable for 99% + of use cases, if you need finer control over + your Linode's disks, see the [List disks](https://techdocs.akamai.com/linode-api/reference/get-linode-disks) + operations. + example: 81920 + readOnly: true + gpus: + type: integer + description: | + __Read-only__ The number of gpus this Linode has access to. + example: 0 + readOnly: true + memory: + type: integer + description: |- + __Read-only__ The amount of RAM, in MB, this Linode has access to. + + Typically, a Linode boots with all of its available RAM, but this can be configured in a Config profile. See the [List config profiles](https://techdocs.akamai.com/linode-api/reference/get-linode-configs) operations and the LinodeConfig object for more information. + example: 4096 + readOnly: true + transfer: + type: integer + description: | + __Read-only__ The amount of network transfer this Linode is + allotted each month. + example: 4000 + readOnly: true + vcpus: + type: integer + description: | + __Read-only__ The number of vcpus this Linode has access to. + example: 2 + readOnly: true + status: + type: string + description: | + __Read-only__ A brief description of this Linode's current state. + This field may change without direct action from + you. For example, when a Linode goes into maintenance + mode its status will display "stopped". + example: running + readOnly: true + enum: + - running + - offline + - booting + - rebooting + - shutting_down + - provisioning + - deleting + - migrating + - rebuilding + - cloning + - restoring + - stopped + - billing_suspension + x-linode-cli-color: + billing_suspension: red + default_: yellow + offline: red + running: green + x-linode-cli-display: 6 + updated: + type: string + description: | + __Read-only__ When this Linode was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + watchdog_enabled: + type: boolean + description: | + The watchdog, named Lassie, is a Shutdown Watchdog that monitors + your Linode and will reboot it if it powers off + unexpectedly. It works by issuing a boot job when + your Linode powers off without a shutdown job being + responsible. To prevent a loop, Lassie will give + up if there have been more than 5 boot jobs issued + within 15 minutes. + example: true + x-linode-ref-name: linode + - type: object + description: | + A domain zonefile in our DNS system. You must own the domain name and + tell your registrar to use Linode's nameservers in order + for a domain in our system to be treated as authoritative. + x-akamai: + file-path: schemas/domain.yaml + title: Domain + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This Domain's unique ID + example: 1234 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of tags applied to this object. Tags are for organizational + purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + type: + type: string + description: | + Whether this Domain represents the authoritative source + of information for the domain it describes ("master"), + or whether it is a read-only copy of a master ("slave"). + example: master + enum: + - master + - slave + x-linode-cli-display: 3 + description: + type: string + description: | + A description for this Domain. This is for display purposes only. + example: null + minLength: 1 + maxLength: 253 + axfr_ips: + type: array + description: |- + The list of IPs that may perform a zone transfer for this Domain. The total combined length of all data within this array cannot exceed 1000 characters. + + __Note__: This is potentially dangerous, and should be set to an empty list unless you intend to use it. + example: [] + items: + type: string + format: ip + domain: + type: string + description: | + The domain this Domain represents. Domain labels cannot be + longer than 63 characters and must conform to [RFC1035](https://tools.ietf.org/html/rfc1035). + Domains must be unique on Linode's platform, including + across different Linode accounts; there cannot be + two Domains representing the same domain. + example: example.org + minLength: 1 + maxLength: 253 + pattern: ^(\*\.)?([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+)$ + x-linode-cli-display: 2 + x-linode-filterable: true + expire_sec: + type: integer + description: |- + The amount of time in seconds that may pass before this Domain is no longer authoritative. + + - Valid values are 0, 30, 120, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200. + + - Any other value is rounded up to the nearest valid value. + + - A value of 0 is equivalent to the default value of 1209600. + example: 300 + default: 0 + group: + type: string + description: | + The group this Domain belongs to. This is for display purposes + only. + example: null + minLength: 1 + maxLength: 50 + deprecated: true + x-linode-filterable: true + master_ips: + type: array + description: | + The IP addresses representing the master DNS for this Domain. + At least one value is required for `type` slave + Domains. The total combined length of all data within + this array cannot exceed 1000 characters. + example: [] + items: + type: string + format: ip + refresh_sec: + type: integer + description: |- + The amount of time in seconds before this Domain should be refreshed. + + - Valid values are 0, 30, 120, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200. + + - Any other value is rounded up to the nearest valid value. + + - A value of 0 is equivalent to the default value of 14400. + example: 300 + default: 0 + retry_sec: + type: integer + description: |- + The interval, in seconds, at which a failed refresh should be retried. + + - Valid values are 0, 30, 120, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200. + + - Any other value is rounded up to the nearest valid value. + + - A value of 0 is equivalent to the default value of 14400. + example: 300 + default: 0 + soa_email: + type: string + description: | + Start of Authority email address. This is required for `type` + master Domains. + example: admin@example.org + format: email + x-linode-cli-display: 5 + status: + type: string + description: | + Used to control whether this Domain is currently being rendered. + example: active + default: active + enum: + - disabled + - active + x-linode-cli-color: + active: green + default_: red + disabled: yellow + edit_mode: yellow + x-linode-cli-display: 4 + ttl_sec: + type: integer + description: |- + "Time to Live" - the amount of time in seconds that this Domain's records may be cached by resolvers or other domain servers. + + - Valid values are 0, 30, 120, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200. + - Any other value is rounded up to the nearest valid value. + - A value of 0 is equivalent to the default value of 86400. + example: 300 + default: 0 + x-linode-ref-name: domain + - type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational + purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on + the Volume's label. Path is /dev/disk/by-id/scsi-0Linode_Volume_ + + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that + Linode will be displayed here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the + label of that Linode will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-linode-ref-name: volume + - type: object + description: | + Linode's load balancing solution. Can handle multiple ports, SSL + termination, and any number of backends. NodeBalancer + ports are configured with NodeBalancer Configs, and + each config is given one or more NodeBalancer Node that + accepts traffic. The traffic should be routed to the NodeBalancer's + ip address, the NodeBalancer will handle routing individual + requests to backends. + x-akamai: + file-path: schemas/node-balancer.yaml + title: NodeBalancer + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ This NodeBalancer's unique ID. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational + purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + client_conn_throttle: + type: integer + description: | + Throttle connections per second. Set to 0 (zero) to disable + throttling. + example: 0 + minimum: 0 + maximum: 20 + x-linode-cli-display: 6 + created: + type: string + description: | + __Read-only__ When this NodeBalancer was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + host: + type: string + description: | + __Read-only__ This NodeBalancer's hostname, beginning with its + IP address and ending with _.ip.linodeusercontent.com_. + example: 192.0.2.1.ip.linodeusercontent.com + readOnly: true + x-linode-cli-display: 4 + ipv4: + type: string + description: | + __Read-only__ This NodeBalancer's public IPv4 address. + example: 203.0.113.1 + readOnly: true + format: ip + x-linode-cli-display: 5 + x-linode-filterable: true + ipv6: + type: string + description: | + __Read-only__ This NodeBalancer's public IPv6 address. + example: null + nullable: true + readOnly: true + format: ip + x-linode-cli-display: 6 + label: + type: string + description: | + This NodeBalancer's label. These must be unique on your Account. + example: balancer12345 + minLength: 3 + maxLength: 32 + pattern: '[a-zA-Z0-9-_]{3,32}' + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + __Read-only__ The Region where this NodeBalancer is located. NodeBalancers + only support backends in the same Region. + example: us-east + readOnly: true + x-linode-cli-display: 3 + x-linode-filterable: true + transfer: + type: object + description: | + __Read-only__ Information about the amount of transfer this NodeBalancer + has had so far this month. + additionalProperties: false + readOnly: true + properties: + in: + type: number + description: | + __Read-only__ The total outbound transfer, in MB, used for + this NodeBalancer this month. + example: 28.91200828552246 + nullable: true + readOnly: true + out: + type: number + description: | + __Read-only__ The total inbound transfer, in MB, used for + this NodeBalancer this month. + example: 3.5487728118896484 + nullable: true + readOnly: true + total: + type: number + description: | + __Read-only__ The total transfer, in MB, used by this NodeBalancer + this month. + example: 32.46078109741211 + nullable: true + readOnly: true + updated: + type: string + description: | + __Read-only__ When this NodeBalancer was last updated. + example: '2018-03-01T00:01:01' + readOnly: true + format: date-time + x-linode-ref-name: nodeBalancer + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-tagged-objects + security: + - personalAccessToken: [] + - oauth: + - account:read_only + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/tags/$tagLabel + x-linode-cli-command: view + x-linode-cli-skip: true + x-original-op-id: getTaggedObjects + x-original-op-title: Tagged Objects List + delete: + operationId: delete-ag + summary: Delete a tag + tags: + - Tags + 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. + + + --- + + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Tag deleted. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-ag + security: + - personalAccessToken: [] + - oauth: + - account:read_write + x-linode-cli-action: + - delete + - rm + x-original-op-id: deleteTag + x-original-op-title: Tag Delete + x-linode-cli-command: tags + /volumes: + x-akamai: + file-path: paths/volumes.yaml + path-info: /volumes + post: + operationId: post-volume + summary: Create a volume + tags: + - Volumes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: volumes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The requested initial state of a new Volume. + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - label + properties: + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + 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: '{{config_id}}' + label: + type: string + description: | + The Volume's label, which is also used in the `filesystem_path` of the resulting volume. + example: '{{label}}' + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + 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: '{{linode_id}}' + region: + type: string + description: | + The Region to deploy this Volume in. This is only required if a linode_id is not given. + example: '{{region}}' + size: + type: integer + description: | + The initial size of this volume, in GB. Be aware that volumes may only be resized up after + creation. + example: '{{size}}' + default: 20 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + x-linode-cli-allowed-defaults: + - region + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Creating Volume. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + 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 + x-linode-charge: true + x-linode-cli-action: create + x-linode-grant: add_volumes + x-original-op-id: createVolume + x-original-op-title: Volume Create + get: + operationId: get-volumes + summary: List volumes + tags: + - Volumes + description: |- + Returns a paginated list of Volumes you have permission to view. + + + --- + + + - __OAuth__. + + ``` + volumes:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: volumes:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns an array of all Volumes on your Account. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes + only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's + label. Path is /dev/disk/by-id/scsi-0Linode_Volume_ + + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will + be displayed here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label + of that Linode will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-volumes + security: + - personalAccessToken: [] + - oauth: + - volumes:read_only + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/volumes + - lang: CLI + source: linode-cli volumes list + x-linode-cli-action: + - list + - ls + x-linode-grant: read_only + x-original-op-id: getVolumes + x-original-op-title: Volumes List + x-linode-cli-command: volumes + /volumes/{volumeId}: + x-akamai: + file-path: paths/volume.yaml + path-info: /volumes/{volumeId} + parameters: + - name: volumeId + in: path + description: | + ID of the Volume to look up. + example: '{{volumeId}}' + x-akamai: + file-path: parameters/volume-id-path-a4b5473e.yaml + required: true + schema: + type: integer + get: + operationId: get-volume + summary: Get a volume + tags: + - Volumes + description: |- + Get information about a single Volume. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: volumes:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a single Volume object. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + links: + attach: + operationId: post-attach-volume + parameters: + volumeID: $request.body#/id + clone: + operationId: post-clone-volume + parameters: + volumeId: $request.body#/id + detach: + operationId: post-attach-volume + parameters: + volumeId: $request.body#/id + resize: + operationId: post-resize-volume + parameters: + volumeId: $request.body#/id + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_only + 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 + x-linode-cli-action: view + x-linode-grant: read_only + x-original-op-id: getVolume + x-original-op-title: Volume View + put: + operationId: put-volume + summary: Update a volume + tags: + - Volumes + description: |- + Updates a Volume that you have permission to `read_write`. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: volumes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + If any updated field fails to pass validation, the Volume will not be updated. + required: true + content: + application/json: + schema: + allOf: + - type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + - type: object + properties: + linode_id: + readOnly: true + size: + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The updated Volume. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + 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 + x-linode-cli-action: update + x-linode-grant: read_write + x-original-op-id: updateVolume + x-original-op-title: Volume Update + delete: + operationId: delete-volume + summary: Delete a volume + tags: + - Volumes + 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. + + + --- + + + - __OAuth__. + + ``` + volumes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: volumes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Volume deletion successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + 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 + x-linode-cli-action: + - delete + - rm + x-linode-grant: read_write + x-original-op-id: deleteVolume + x-original-op-title: Volume Delete + x-linode-cli-command: volumes + /volumes/{volumeId}/attach: + x-akamai: + file-path: paths/attach.yaml + path-info: /volumes/{volumeId}/attach + parameters: + - name: volumeId + in: path + description: | + ID of the Volume to attach. + example: '{{volumeId}}' + x-akamai: + file-path: parameters/volume-id-path-62b4501e.yaml + required: true + schema: + type: integer + post: + operationId: post-attach-volume + summary: Attach a volume + tags: + - Volumes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes attach + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes attach + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: |- + volumes:read_write + linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Volume to attach to a Linode. + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - linode_id + properties: + 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: '{{config_id}}' + linode_id: + type: integer + description: | + The ID of the Linode to attach the volume to. + example: '{{linode_id}}' + 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. + example: '{{persist_across_boots}}' + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Volume was attached to a Linode. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-attach-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + - linodes:read_write + 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 + x-linode-cli-action: attach + x-original-op-id: attachVolume + x-original-op-title: Volume Attach + x-linode-cli-command: volumes + /volumes/{volumeId}/clone: + x-akamai: + file-path: paths/volume-clone.yaml + path-info: /volumes/{volumeId}/clone + parameters: + - name: volumeId + in: path + description: | + ID of the Volume to clone. + example: '{{volumeId}}' + x-akamai: + file-path: parameters/volume-id-path-1f2bbcd1.yaml + required: true + schema: + type: integer + post: + operationId: post-clone-volume + summary: Clone a volume + tags: + - Volumes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes clone + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes clone + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: volumes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The requested state your Volume will be cloned into. + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - label + properties: + label: + type: string + description: | + The Volume's label is for display purposes only. + example: '{{label}}' + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Clone started. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-clone-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + 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 + x-linode-charge: true + x-linode-cli-action: clone + x-linode-grant: add_volumes + x-original-op-id: cloneVolume + x-original-op-title: Volume Clone + x-linode-cli-command: volumes + /volumes/{volumeId}/detach: + x-akamai: + file-path: paths/detach.yaml + path-info: /volumes/{volumeId}/detach + parameters: + - name: volumeId + in: path + description: | + ID of the Volume to detach. + example: '{{volumeId}}' + x-akamai: + file-path: parameters/volume-id-path-e125a1de.yaml + required: true + schema: + type: integer + post: + operationId: post-detach-volume + summary: Detach a volume + tags: + - Volumes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes detach + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + linodes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes detach + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: |- + volumes:read_write + linodes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Volume was detached from a Linode. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-detach-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + - linodes:read_write + 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 + x-linode-cli-action: detach + x-original-op-id: detachVolume + x-original-op-title: Volume Detach + x-linode-cli-command: volumes + /volumes/{volumeId}/resize: + x-akamai: + file-path: paths/volume-resize.yaml + path-info: /volumes/{volumeId}/resize + parameters: + - name: volumeId + in: path + description: | + ID of the Volume to resize. + example: '{{volumeId}}' + x-akamai: + file-path: parameters/volume-id-path-e4f0f1b5.yaml + required: true + schema: + type: integer + post: + operationId: post-resize-volume + summary: Resize a volume + tags: + - Volumes + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli volumes resize + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + volumes:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli volumes resize + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: volumes:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + The requested size to increase your Volume to. + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + required: + - size + properties: + size: + type: integer + description: | + The Volume's size, in GiB. + example: '{{size}}' + maximum: 10240 + x-linode-cli-display: 4 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Volume resize started. + content: + application/json: + schema: + type: object + description: | + A Block Storage Volume associated with your Account. + x-akamai: + file-path: schemas/volume.yaml + title: Volume + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of this Volume. + example: 12345 + readOnly: true + x-linode-cli-display: 1 + tags: + type: array + description: | + An array of Tags applied to this object. Tags are for organizational purposes only. + example: + - example tag + - another example + items: + type: string + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ When this Volume was created. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + filesystem_path: + type: string + description: | + __Read-only__ The full filesystem path for the Volume based on the Volume's label. + Path is /dev/disk/by-id/scsi-0Linode_Volume_ + Volume label. + example: /dev/disk/by-id/scsi-0Linode_Volume_my-volume + readOnly: true + hardware_type: + type: string + description: | + __Read-only__ The storage type of this Volume. + example: nvme + readOnly: true + enum: + - hdd + - nvme + label: + type: string + description: | + The Volume's label is for display purposes only. + example: my-volume + minLength: 1 + maxLength: 32 + pattern: ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$ + x-linode-cli-display: 2 + x-linode-filterable: true + linode_id: + type: integer + description: | + If a Volume is attached to a specific Linode, the ID of that Linode will be displayed + here. + example: 12346 + nullable: true + x-linode-cli-display: 6 + linode_label: + type: string + description: | + __Read-only__ If a Volume is attached to a specific Linode, the label of that Linode + will be displayed here. + example: linode123 + nullable: true + readOnly: true + x-linode-cli-display: 7 + region: + type: string + description: | + __Read-only__ The unique ID of this Region. + example: us-east + readOnly: true + x-linode-cli-display: 5 + size: + type: integer + description: | + The Volume's size, in GiB. + example: 30 + maximum: 10240 + x-linode-cli-display: 4 + status: + type: string + description: |- + __Read-only__ The current status of the volume. Can be one of: + + - `creating` - the Volume is being created and is not yet available + for use. + - `active` - the Volume is online and available for use. + - `resizing` - the Volume is in the process of upgrading + its current capacity. + example: active + readOnly: true + enum: + - creating + - active + - resizing + x-linode-cli-color: + active: green + contact_support: red + default_: yellow + x-linode-cli-display: 3 + updated: + type: string + description: | + __Read-only__ When this Volume was last updated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-resize-volume + security: + - personalAccessToken: [] + - oauth: + - volumes:read_write + 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 + x-linode-charge: true + x-linode-cli-action: resize + x-original-op-id: resizeVolume + x-original-op-title: Volume Resize + x-linode-cli-command: volumes + /vpcs: + x-akamai: + file-path: paths/vpcs.yaml + path-info: /vpcs + post: + servers: + - url: https://api.linode.com/v4 + operationId: post-vpc + summary: Create a VPC + tags: + - VPCs + description: |- + Create a new VPC and optionally associated VPC Subnets. + + - Users must have the `add_vpc` grant to access this operation. + - 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 operations: + + - [Create a Linode](https://techdocs.akamai.com/linode-api/reference/post-linode-instance) + - [Create a config profile](https://techdocs.akamai.com/linode-api/reference/post-add-linode-config) + - [Update a config profile](https://techdocs.akamai.com/linode-api/reference/put-linode-config) + - [Add a configuration profile interface](https://techdocs.akamai.com/linode-api/reference/post-linode-config-interface) + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + VPC Create request object. + required: true + content: + application/json: + schema: + allOf: + - required: + - label + - region + - properties: + subnets: + required: + - ipv4 + - label + - type: object + description: | + An object describing a VPC belonging to the Account. + x-akamai: + file-path: schemas/vpc.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + description: + type: string + description: | + A written description to help distinguish the VPC. + example: A description of my VPC. + default: '' + maxLength: 255 + x-linode-cli-display: 3 + created: + type: string + description: | + __Read-only__ The date-time of VPC creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The Region for the VPC. + example: us-east + x-linode-cli-display: 4 + x-linode-filterable: true + subnets: + type: array + description: | + A list of subnets associated with the VPC. + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning + that the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The new VPC. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC belonging to the Account. + x-akamai: + file-path: schemas/vpc.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + description: + type: string + description: | + A written description to help distinguish the VPC. + example: A description of my VPC. + default: '' + maxLength: 255 + x-linode-cli-display: 3 + created: + type: string + description: | + __Read-only__ The date-time of VPC creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The Region for the VPC. + example: us-east + x-linode-cli-display: 4 + x-linode-filterable: true + subnets: + type: array + description: | + A list of subnets associated with the VPC. + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning + that the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-vpc + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: create + x-linode-grant: add_vpcs + x-original-op-id: createVPC + x-original-op-title: VPC Create + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpcs + summary: List VPCs + tags: + - VPCs + description: | + Display all VPCs on your account. + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of VPC objects. + content: + application/json: + schema: + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - properties: + data: + type: array + items: + type: object + description: | + An object describing a VPC belonging to the Account. + x-akamai: + file-path: schemas/vpc.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + description: + type: string + description: | + A written description to help distinguish the VPC. + example: A description of my VPC. + default: '' + maxLength: 255 + x-linode-cli-display: 3 + created: + type: string + description: | + __Read-only__ The date-time of VPC creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The Region for the VPC. + example: us-east + x-linode-cli-display: 4 + x-linode-filterable: true + subnets: + type: array + description: | + A list of subnets associated with the VPC. + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, + meaning that the Linode was powered + on using the Configuration Profile + to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpcs + security: + - personalAccessToken: [] + - oauth: [] + x-code-samples: + - lang: Shell + source: |- + curl https://api.linode.com/v4/vpcs \ + -H "Authorization: Bearer $TOKEN" + - lang: CLI + source: linode-cli vpcs list + x-linode-cli-action: + - list + - ls + x-original-op-id: getVPCs + x-original-op-title: VPCs List + x-linode-cli-command: vpcs + /vpcs/ips: + x-akamai: + file-path: paths/vpcs-ips.yaml + path-info: /vpcs/ips + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpcs-ips + summary: List VPC IP addresses + tags: + - IP addresses + 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. + + + --- + + + - __OAuth__. + + ``` + ips:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: ips:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of VPC interface IP addresses. + content: + application/json: + schema: + additionalProperties: false + properties: + data: + type: array + items: + description: | + The response data for the VPC IP Addresses List and View operations. + x-akamai: + file-path: schemas/ip-addresses-vpc.yaml + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through + a GET endpoint, the results are wrapped in this envelope + which includes metadata about those results. Results are + presented within a `data` array. See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - type: object + description: | + A VPC IP address that exists in Linode's system, specific to the response + for the [List VPC IP addresses](https://techdocs.akamai.com/linode-api/reference/get-vpcs-ips) + operation. Returned as an empty set for Linodes that are + not part of a VPC. + properties: + active: + type: boolean + description: | + __Read-only__ Returns `true` if the VPC interface is in use, meaning + that the Linode was powered on using the `config_id` + to which the interface belongs. Otherwise returns `false`. + example: true + readOnly: true + x-linode-filterable: true + address: + type: string + description: | + __Read-only__ An IPv4 address configured for this VPC interface. These + follow the [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) + private address format. Displayed as `null` if an `address_range`. + example: 192.0.2.141 + nullable: true + readOnly: true + format: ip + x-linode-cli-display: 1 + address_range: + type: string + description: | + __Read-only__ A range of IPv4 addresses configured for this VPC interface. + Displayed as `null` if a single `address`. + nullable: true + readOnly: true + config_id: + type: integer + description: | + __Read-only__ The globally general entity identifier for the Linode + configuration profile where the VPC is included. + example: 4567 + readOnly: true + x-linode-filterable: true + gateway: + type: string + description: | + __Read-only__ The default gateway for the VPC subnet that the IP or + IP range belongs to. + example: 192.0.2.1 + nullable: true + readOnly: true + format: ip + interface_id: + type: integer + description: | + __Read-only__ The globally general API entity identifier for the Linode + interface. + example: 2435 + readOnly: true + linode_id: + type: integer + description: | + __Read-only__ The identifier for the Linode the VPC interface currently + belongs to. + example: 123 + readOnly: true + x-linode-cli-display: 6 + x-linode-filterable: true + nat_1_1: + type: string + description: | + __Read-only__ The public IP address used for NAT 1:1 with the VPC. + This is empty if NAT 1:1 isn't used. + example: 192.168.0.42 + readOnly: true + format: ip + prefix: + type: integer + description: | + __Read-only__ The number of bits set in the `subnet_mask`. + example: 24 + nullable: true + readOnly: true + region: + type: string + description: | + __Read-only__ The region of the VPC. + example: us-east + readOnly: true + x-linode-cli-display: 5 + x-linode-filterable: true + subnet_id: + type: integer + description: | + The `id` of the VPC Subnet for this interface. + example: 101 + nullable: false + subnet_mask: + type: string + description: | + __Read-only__ The mask that separates host bits from network bits + for the `address` or `address_range`. + example: 255.255.255.0 + readOnly: true + format: ip + vpc_id: + type: integer + description: | + __Read-only__ The unique globally general API entity identifier for + the VPC. + example: 7654 + readOnly: true + x-linode-filterable: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpcs-ips + security: + - personalAccessToken: [] + - oauth: + - ips:read_only + 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 + x-linode-cli-action: + - ip-list + - ip-ls + x-linode-grant: read_only + x-original-op-id: getAllVPCIPs + x-original-op-title: VPC IP Addresses List + /vpcs/{vpcId}: + x-akamai: + file-path: paths/vpc.yaml + path-info: /vpcs/{vpcId} + parameters: + - name: vpcId + in: path + description: | + The `id` of the VPC. + example: '{{vpcId}}' + x-akamai: + file-path: parameters/vpc-id.yaml + required: true + schema: + type: integer + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpc + summary: Get a VPC + tags: + - VPCs + description: | + Get information about a single VPC. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A VPC object. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC belonging to the Account. + x-akamai: + file-path: schemas/vpc.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + description: + type: string + description: | + A written description to help distinguish the VPC. + example: A description of my VPC. + default: '' + maxLength: 255 + x-linode-cli-display: 3 + created: + type: string + description: | + __Read-only__ The date-time of VPC creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The Region for the VPC. + example: us-east + x-linode-cli-display: 4 + x-linode-filterable: true + subnets: + type: array + description: | + A list of subnets associated with the VPC. + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning + that the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpc + security: + - personalAccessToken: [] + - oauth: [] + 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 + x-linode-cli-action: view + x-original-op-id: getVPC + x-original-op-title: VPC View + put: + servers: + - url: https://api.linode.com/v4 + operationId: put-vpc + summary: Update a VPC + tags: + - VPCs + description: |- + Update an existing VPC. + + - The User accessing this operation must have `read_write` grants to the VPC. + - A successful request triggers a `vpc_update` event. + + To update a VPC's Subnet, run the [Update a VPC subnet](https://techdocs.akamai.com/linode-api/reference/put-vpc-subnet) operation. + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + VPC Update request object. + required: true + content: + application/json: + schema: + type: object + description: | + A VPC Update request object. + additionalProperties: false + properties: + description: + type: string + description: | + A written description to help distinguish the VPC. + example: '{{description}}' + default: '' + maxLength: 255 + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: '{{label}}' + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The updated VPC. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC belonging to the Account. + x-akamai: + file-path: schemas/vpc.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC. + example: 123 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + description: + type: string + description: | + A written description to help distinguish the VPC. + example: A description of my VPC. + default: '' + maxLength: 255 + x-linode-cli-display: 3 + created: + type: string + description: | + __Read-only__ The date-time of VPC creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + label: + type: string + description: |- + The VPC's label, for display purposes only. + + - Needs to be unique among the Account's VPCs. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + region: + type: string + description: | + The Region for the VPC. + example: us-east + x-linode-cli-display: 4 + x-linode-filterable: true + subnets: + type: array + description: | + A list of subnets associated with the VPC. + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning + that the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-vpc + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: update + x-linode-grant: read_write + x-original-op-id: updateVPC + x-original-op-title: VPC Update + delete: + servers: + - url: https://api.linode.com/v4 + operationId: delete-vpc + summary: Delete a VPC + tags: + - VPCs + description: |- + Delete a single VPC and all of its Subnets. + + - The User accessing this operation 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. + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Delete request successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-vpc + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: delete + x-linode-grant: read_write + x-original-op-id: deleteVPC + x-original-op-title: VPC Delete + x-linode-cli-command: vpcs + /vpcs/{vpcId}/ips: + x-akamai: + file-path: paths/vpc-ips.yaml + path-info: /vpcs/{vpcId}/ips + parameters: + - name: vpcId + in: path + description: | + The `id` of the VPC. + example: '{{vpcId}}' + x-akamai: + file-path: parameters/vpc-id.yaml + required: true + schema: + type: integer + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpc-ips + summary: List a VPC's IP addresses + tags: + - IP addresses + description: |- + Returns a paginated list of IP addresses for a single VPC. + + + --- + + + - __OAuth__. + + ``` + ips:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: ips:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The IP addresses for the requested VPC. + content: + application/json: + schema: + description: | + The response data for the VPC IP Addresses List and View operations. + x-akamai: + file-path: schemas/ip-addresses-vpc.yaml + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - type: object + description: | + A VPC IP address that exists in Linode's system, specific to the response for the [List + VPC IP addresses](https://techdocs.akamai.com/linode-api/reference/get-vpcs-ips) + operation. Returned as an empty set for Linodes that are not part + of a VPC. + properties: + active: + type: boolean + description: | + __Read-only__ Returns `true` if the VPC interface is in use, meaning that the Linode + was powered on using the `config_id` to which the interface + belongs. Otherwise returns `false`. + example: true + readOnly: true + x-linode-filterable: true + address: + type: string + description: | + __Read-only__ An IPv4 address configured for this VPC interface. These follow + the [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) + private address format. Displayed as `null` if an `address_range`. + example: 192.0.2.141 + nullable: true + readOnly: true + format: ip + x-linode-cli-display: 1 + address_range: + type: string + description: | + __Read-only__ A range of IPv4 addresses configured for this VPC interface. Displayed + as `null` if a single `address`. + nullable: true + readOnly: true + config_id: + type: integer + description: | + __Read-only__ The globally general entity identifier for the Linode configuration + profile where the VPC is included. + example: 4567 + readOnly: true + x-linode-filterable: true + gateway: + type: string + description: | + __Read-only__ The default gateway for the VPC subnet that the IP or IP range + belongs to. + example: 192.0.2.1 + nullable: true + readOnly: true + format: ip + interface_id: + type: integer + description: | + __Read-only__ The globally general API entity identifier for the Linode interface. + example: 2435 + readOnly: true + linode_id: + type: integer + description: | + __Read-only__ The identifier for the Linode the VPC interface currently belongs + to. + example: 123 + readOnly: true + x-linode-cli-display: 6 + x-linode-filterable: true + nat_1_1: + type: string + description: | + __Read-only__ The public IP address used for NAT 1:1 with the VPC. This is empty + if NAT 1:1 isn't used. + example: 192.168.0.42 + readOnly: true + format: ip + prefix: + type: integer + description: | + __Read-only__ The number of bits set in the `subnet_mask`. + example: 24 + nullable: true + readOnly: true + region: + type: string + description: | + __Read-only__ The region of the VPC. + example: us-east + readOnly: true + x-linode-cli-display: 5 + x-linode-filterable: true + subnet_id: + type: integer + description: | + The `id` of the VPC Subnet for this interface. + example: 101 + nullable: false + subnet_mask: + type: string + description: | + __Read-only__ The mask that separates host bits from network bits for the `address` + or `address_range`. + example: 255.255.255.0 + readOnly: true + format: ip + vpc_id: + type: integer + description: | + __Read-only__ The unique globally general API entity identifier for the VPC. + example: 7654 + readOnly: true + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpc-ips + security: + - personalAccessToken: [] + - oauth: + - ips:read_only + 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 + x-linode-cli-action: + - ip-list + - ip-ls + x-original-op-id: getVPCIPs + x-original-op-title: VPC IP Addresses View + /vpcs/{vpcId}/subnets: + x-akamai: + file-path: paths/subnets.yaml + path-info: /vpcs/{vpcId}/subnets + parameters: + - name: vpcId + in: path + description: | + The `id` of the VPC. + example: '{{vpcId}}' + x-akamai: + file-path: parameters/vpc-id.yaml + required: true + schema: + type: integer + post: + servers: + - url: https://api.linode.com/v4 + operationId: post-vpc-subnet + summary: Create a VPC subnet + tags: + - VPC subnets + description: |- + Create a VPC Subnet. + + - The User accessing this operation 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 operations: + + - [Create a Linode](https://techdocs.akamai.com/linode-api/reference/post-linode-instance) + - [Create a config profile](https://techdocs.akamai.com/linode-api/reference/post-add-linode-config) + - [Update a config profile](https://techdocs.akamai.com/linode-api/reference/put-linode-config) + - [Add a configuration profile interface](https://techdocs.akamai.com/linode-api/reference/post-linode-config-interface) + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs subnet-create + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs subnet-create + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + VPC Subnet Create request object. + required: true + content: + application/json: + schema: + type: object + description: | + VPC Subnet Create request object + additionalProperties: false + required: + - ipv4 + - label + properties: + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: '{{ipv4}}' + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: '{{label}}' + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The new VPC Subnet. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning that + the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-vpc-subnet + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: subnet-create + x-linode-grant: read_write + x-original-op-id: createVPCSubnet + x-original-op-title: VPC Subnet Create + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpc-subnets + summary: List VPC subnets + tags: + - VPC subnets + description: | + Get information about all VPC Subnets associated with a VPC. + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A paginated list of VPC Subnet objects. + content: + application/json: + schema: + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - properties: + data: + type: array + items: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning + that the Linode was powered on using the + Configuration Profile to which the Interface + belongs. Otherwise returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpc-subnets + security: + - personalAccessToken: [] + - oauth: [] + 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 + x-linode-cli-action: + - subnets-list + - subnets-ls + x-original-op-id: getVPCSubnets + x-original-op-title: VPC Subnets List + x-linode-cli-command: vpcs + /vpcs/{vpcId}/subnets/{vpcSubnetId}: + x-akamai: + file-path: paths/vpc-subnet.yaml + path-info: /vpcs/{vpcId}/subnets/{vpcSubnetId} + parameters: + - name: vpcId + in: path + description: | + The `id` of the VPC. + example: '{{vpcId}}' + x-akamai: + file-path: parameters/vpc-id.yaml + required: true + schema: + type: integer + - name: vpcSubnetId + in: path + description: | + The `id` of the VPC Subnet. + example: '{{vpcSubnetId}}' + x-akamai: + file-path: parameters/vpc-subnet-id.yaml + required: true + schema: + type: integer + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-vpc-subnet + summary: Get a VPC subnet + tags: + - VPC subnets + description: | + Get information about a single VPC Subnet. + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + A VPC Subnet object. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning that + the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-vpc-subnet + security: + - personalAccessToken: [] + - oauth: [] + 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' + x-linode-cli-action: subnet-view + x-original-op-id: getVPCSubnet + x-original-op-title: VPC Subnet View + put: + servers: + - url: https://api.linode.com/v4 + operationId: put-vpc-subnet + summary: Update a VPC subnet + tags: + - VPC subnets + description: |- + Update a VPC Subnet. + + - The User accessing this operation must have `read_write` grants to the VPC. + - A successful request triggers a `subnet_update` event. + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs subnet-update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs subnet-update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + VPC Update request object. + required: true + content: + application/json: + schema: + type: object + description: | + A VPC Subnet Update request object. + additionalProperties: false + properties: + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: '{{label}}' + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The updated VPC Subnet. + content: + application/json: + schema: + type: object + description: | + An object describing a VPC Subnet. + x-akamai: + file-path: schemas/vpc-subnet.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The unique ID of the VPC Subnet. + example: 456 + readOnly: true + x-linode-cli-display: 1 + x-linode-filterable: true + created: + type: string + description: | + __Read-only__ The date-time of VPC Subnet creation. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-filterable: true + ipv4: + type: string + description: |- + IPv4 range in CIDR canonical form. + + - The range must belong to a private address space as defined in [RFC1918](https://datatracker.ietf.org/doc/html/rfc1918). + - Allowed prefix lengths: 1-29. + - The range must not overlap with 192.168.128.0/17. + - The range must not overlap with other Subnets on the same VPC. + example: 10.0.1.0/24 + format: ip + x-linode-cli-display: 3 + label: + type: string + description: |- + The VPC Subnet's label, for display purposes only. + + - Must be unique among the VPC's Subnets. + - Can only contain ASCII letters, numbers, and hyphens (`-`). You can't use two consecutive hyphens (`--`). + example: cool-vpc-subnet + minLength: 1 + maxLength: 64 + x-linode-cli-display: 2 + x-linode-filterable: true + linodes: + type: array + description: |- + __Read-only__ An array of Linode IDs assigned to the VPC Subnet. + + A Linode is assigned to a VPC Subnet if it has a Configuration Profile with a `vpc` purpose interface with the subnet's `subnet_id`. Even if the Configuration Profile is not active, meaning the Linode does not have access to the Subnet, the Linode still appears in this array. + readOnly: true + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of a Linode assigned to the VPC Subnet. + example: 111 + interfaces: + type: array + description: | + An array of Interfaces assigned to the Linode. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the interface + example: 421 + active: + type: boolean + description: | + Returns `true` if the Interface is in use, meaning that + the Linode was powered on using the Configuration + Profile to which the Interface belongs. Otherwise + returns `false`. + example: true + x-linode-cli-display: 5 + updated: + type: string + description: | + __Read-only__ The date-time of the most recent VPC Subnet update. + example: '2023-09-11T00:00:00' + nullable: true + readOnly: true + format: date-time + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-vpc-subnet + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: subnet-update + x-linode-grant: read_write + x-original-op-id: updateVPCSubnet + x-original-op-title: VPC Subnet Update + delete: + servers: + - url: https://api.linode.com/v4 + operationId: delete-vpc-subnet + summary: Delete a VPC subnet + tags: + - VPC subnets + description: |- + Delete a single VPC Subnet. + + The user accessing this operation 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. + + + --- + + + - __CLI__. + + ``` + linode-cli vpcs subnet-delete + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + vpc:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli vpcs subnet-delete + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: vpc:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Delete request successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/delete-vpc-subnet + security: + - personalAccessToken: [] + - oauth: + - vpc:read_write + 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 + x-linode-cli-action: subnet-delete + x-linode-grant: read_write + x-original-op-id: deleteVPCSubnet + x-original-op-title: VPC Subnet Delete + x-linode-cli-command: vpcs + /account: + x-akamai: + file-path: paths/account.yaml + path-info: /account + get: + operationId: get-account + summary: Get your account + tags: + - Account + description: |- + Returns the contact and billing information related to your Account. + + + --- + + + - __CLI__. + + ``` + linode-cli account view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli account view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a single Account object. + content: + application/json: + schema: + type: object + description: | + Account object + x-akamai: + file-path: schemas/account.yaml + additionalProperties: false + properties: + active_promotions: + type: array + readOnly: true + items: + type: object + 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. + + Simply 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. + x-akamai: + file-path: schemas/promotion.yaml + additionalProperties: false + readOnly: true + properties: + summary: + type: string + description: | + Short details of this promotion. + example: $10 off your Linode a month! + x-linode-cli-display: 10 + description: + type: string + description: | + A detailed description of this promotion. + example: Receive up to $10 off your services every month for 6 months! Unused credits + will expire once this promotion period ends. + credit_monthly_cap: + type: string + description: | + The amount available to spend per month. + example: '10.00' + x-linode-cli-display: 5 + credit_remaining: + type: string + description: | + The total amount of credit left for this promotion. + example: '50.00' + x-linode-cli-display: 3 + expire_dt: + type: string + description: | + When this promotion's credits expire. + example: '2018-01-31T23:59:59' + x-linode-cli-display: 2 + image_url: + type: string + description: | + The location of an image for this promotion. + example: https://linode.com/10_a_month_promotion.svg + service_type: + 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 + - placement_group + - objectstorage + - transfer_tx + x-linode-cli-display: 1 + this_month_credit_remaining: + type: string + description: | + The amount of credit left for this month for this promotion. + example: '10.00' + x-linode-cli-display: 4 + active_since: + type: string + description: | + __Read-only__ The date and time the account was activated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + address_1: + type: string + description: | + First line of this Account's billing address. + example: 123 Main Street + maxLength: 64 + address_2: + type: string + description: | + Second line of this Account's billing address. + example: Suite A + maxLength: 64 + balance: + type: number + description: | + __Read-only__ This Account's balance, in US dollars. + example: 200 + readOnly: true + x-linode-cli-display: 4 + balance_uninvoiced: + type: number + description: | + __Read-only__ 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 + readOnly: true + x-linode-cli-display: 4 + billing_source: + type: string + description: | + __Read-only__ 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 + readOnly: true + enum: + - akamai + - linode + capabilities: + type: array + description: | + __Read-only__ A list of capabilities your account supports. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + - Placement Groups + readOnly: true + items: + type: string + city: + type: string + description: | + The city for this Account's billing address. + example: Philadelphia + maxLength: 24 + company: + type: string + description: |- + The company name associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: Linode LLC + maxLength: 128 + country: + type: string + description: | + The two-letter ISO 3166 country code of this Account's billing address. + example: US + credit_card: + type: object + description: | + __Read-only__ Credit Card information associated with this Account. + additionalProperties: false + readOnly: true + properties: + expiry: + type: string + description: | + The expiration month and year of the credit card. + example: 11/2022 + last_four: + type: string + description: | + The last four digits of the credit card associated with this Account. + example: 1111 + email: + type: string + description: | + The email address of the person associated with this Account. + example: john.smith@linode.com + maxLength: 128 + x-linode-cli-display: 3 + euuid: + type: string + description: | + __Read-only__ An external unique identifier for this account. + example: E1AF5EEC-526F-487D-B317EBEB34C87D71 + readOnly: true + format: uuid + first_name: + type: string + description: |- + The first name of the person associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: John + maxLength: 50 + 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: `<` `>` `(` `)` `"` `=` + example: Smith + maxLength: 50 + x-linode-cli-display: 2 + phone: + type: string + description: | + The phone number associated with this Account. + example: 215-555-1212 + maxLength: 32 + 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. + example: PA + maxLength: 24 + 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 (`""`). + example: ATU99999999 + maxLength: 25 + zip: + type: string + description: |- + The zip code of this Account's billing address. The following restrictions apply: + + - Can only contain ASCII letters, numbers, and hyphens (`-`). + - Must not contain more than 9 letter or number characters. + example: 19102-1234 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-account + security: + - personalAccessToken: [] + - oauth: + - account:read_only + x-code-samples: + - lang: Shell + source: |- + curl -H "Authorization: Bearer $TOKEN" \ + https://api.linode.com/v4/account + - lang: CLI + source: linode-cli account view + x-linode-cli-action: view + x-linode-grant: read_only + x-original-op-id: getAccount + x-original-op-title: Account View + put: + operationId: put-account + summary: Update your account + tags: + - Account + 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](https://www.linode.com/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. + + + --- + + + - __CLI__. + + ``` + linode-cli account update + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli account update + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Updated contact and billing information. + required: true + content: + application/json: + schema: + type: object + description: | + Account object + x-akamai: + file-path: schemas/account.yaml + additionalProperties: false + properties: + active_promotions: + type: array + readOnly: true + items: + type: object + 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. + + Simply 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. + x-akamai: + file-path: schemas/promotion.yaml + additionalProperties: false + readOnly: true + properties: + summary: + type: string + description: | + Short details of this promotion. + example: $10 off your Linode a month! + x-linode-cli-display: 10 + description: + type: string + description: | + A detailed description of this promotion. + example: Receive up to $10 off your services every month for 6 months! Unused credits will + expire once this promotion period ends. + credit_monthly_cap: + type: string + description: | + The amount available to spend per month. + example: '10.00' + x-linode-cli-display: 5 + credit_remaining: + type: string + description: | + The total amount of credit left for this promotion. + example: '50.00' + x-linode-cli-display: 3 + expire_dt: + type: string + description: | + When this promotion's credits expire. + example: '2018-01-31T23:59:59' + x-linode-cli-display: 2 + image_url: + type: string + description: | + The location of an image for this promotion. + example: https://linode.com/10_a_month_promotion.svg + service_type: + 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 + - placement_group + - objectstorage + - transfer_tx + x-linode-cli-display: 1 + this_month_credit_remaining: + type: string + description: | + The amount of credit left for this month for this promotion. + example: '10.00' + x-linode-cli-display: 4 + active_since: + type: string + description: | + __Read-only__ The date and time the account was activated. + example: '{{active_since}}' + readOnly: true + format: date-time + address_1: + type: string + description: | + First line of this Account's billing address. + example: '{{address_1}}' + maxLength: 64 + address_2: + type: string + description: | + Second line of this Account's billing address. + example: '{{address_2}}' + maxLength: 64 + balance: + type: number + description: | + __Read-only__ This Account's balance, in US dollars. + example: '{{balance}}' + readOnly: true + x-linode-cli-display: 4 + balance_uninvoiced: + type: number + description: | + __Read-only__ 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: '{{balance_uninvoiced}}' + readOnly: true + x-linode-cli-display: 4 + billing_source: + type: string + description: | + __Read-only__ 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: '{{billing_source}}' + readOnly: true + enum: + - akamai + - linode + capabilities: + type: array + description: | + __Read-only__ A list of capabilities your account supports. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + - Placement Groups + readOnly: true + items: + type: string + city: + type: string + description: | + The city for this Account's billing address. + example: '{{city}}' + maxLength: 24 + company: + type: string + description: |- + The company name associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: '{{company}}' + maxLength: 128 + country: + type: string + description: | + The two-letter ISO 3166 country code of this Account's billing address. + example: '{{country}}' + credit_card: + type: object + description: | + __Read-only__ Credit Card information associated with this Account. + additionalProperties: false + readOnly: true + properties: + expiry: + type: string + description: | + The expiration month and year of the credit card. + example: 11/2022 + last_four: + type: string + description: | + The last four digits of the credit card associated with this Account. + example: 1111 + email: + type: string + description: | + The email address of the person associated with this Account. + example: '{{email}}' + maxLength: 128 + x-linode-cli-display: 3 + euuid: + type: string + description: | + __Read-only__ An external unique identifier for this account. + example: '{{euuid}}' + readOnly: true + format: uuid + first_name: + type: string + description: |- + The first name of the person associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: '{{first_name}}' + maxLength: 50 + 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: `<` `>` `(` `)` `"` `=` + example: '{{last_name}}' + maxLength: 50 + x-linode-cli-display: 2 + phone: + type: string + description: | + The phone number associated with this Account. + example: '{{phone}}' + maxLength: 32 + 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. + example: '{{state}}' + maxLength: 24 + 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 (`""`). + example: '{{tax_id}}' + maxLength: 25 + zip: + type: string + description: |- + The zip code of this Account's billing address. The following restrictions apply: + + - Can only contain ASCII letters, numbers, and hyphens (`-`). + - Must not contain more than 9 letter or number characters. + example: '{{zip}}' + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The updated Account. + content: + application/json: + schema: + type: object + description: | + Account object + x-akamai: + file-path: schemas/account.yaml + additionalProperties: false + properties: + active_promotions: + type: array + readOnly: true + items: + type: object + 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. + + Simply 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. + x-akamai: + file-path: schemas/promotion.yaml + additionalProperties: false + readOnly: true + properties: + summary: + type: string + description: | + Short details of this promotion. + example: $10 off your Linode a month! + x-linode-cli-display: 10 + description: + type: string + description: | + A detailed description of this promotion. + example: Receive up to $10 off your services every month for 6 months! Unused credits + will expire once this promotion period ends. + credit_monthly_cap: + type: string + description: | + The amount available to spend per month. + example: '10.00' + x-linode-cli-display: 5 + credit_remaining: + type: string + description: | + The total amount of credit left for this promotion. + example: '50.00' + x-linode-cli-display: 3 + expire_dt: + type: string + description: | + When this promotion's credits expire. + example: '2018-01-31T23:59:59' + x-linode-cli-display: 2 + image_url: + type: string + description: | + The location of an image for this promotion. + example: https://linode.com/10_a_month_promotion.svg + service_type: + 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 + - placement_group + - objectstorage + - transfer_tx + x-linode-cli-display: 1 + this_month_credit_remaining: + type: string + description: | + The amount of credit left for this month for this promotion. + example: '10.00' + x-linode-cli-display: 4 + active_since: + type: string + description: | + __Read-only__ The date and time the account was activated. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + address_1: + type: string + description: | + First line of this Account's billing address. + example: 123 Main Street + maxLength: 64 + address_2: + type: string + description: | + Second line of this Account's billing address. + example: Suite A + maxLength: 64 + balance: + type: number + description: | + __Read-only__ This Account's balance, in US dollars. + example: 200 + readOnly: true + x-linode-cli-display: 4 + balance_uninvoiced: + type: number + description: | + __Read-only__ 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 + readOnly: true + x-linode-cli-display: 4 + billing_source: + type: string + description: | + __Read-only__ 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 + readOnly: true + enum: + - akamai + - linode + capabilities: + type: array + description: | + __Read-only__ A list of capabilities your account supports. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + - Placement Groups + readOnly: true + items: + type: string + city: + type: string + description: | + The city for this Account's billing address. + example: Philadelphia + maxLength: 24 + company: + type: string + description: |- + The company name associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: Linode LLC + maxLength: 128 + country: + type: string + description: | + The two-letter ISO 3166 country code of this Account's billing address. + example: US + credit_card: + type: object + description: | + __Read-only__ Credit Card information associated with this Account. + additionalProperties: false + readOnly: true + properties: + expiry: + type: string + description: | + The expiration month and year of the credit card. + example: 11/2022 + last_four: + type: string + description: | + The last four digits of the credit card associated with this Account. + example: 1111 + email: + type: string + description: | + The email address of the person associated with this Account. + example: john.smith@linode.com + maxLength: 128 + x-linode-cli-display: 3 + euuid: + type: string + description: | + __Read-only__ An external unique identifier for this account. + example: E1AF5EEC-526F-487D-B317EBEB34C87D71 + readOnly: true + format: uuid + first_name: + type: string + description: |- + The first name of the person associated with this Account. + + Must not include any of the following characters: `<` `>` `(` `)` `"` `=` + example: John + maxLength: 50 + 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: `<` `>` `(` `)` `"` `=` + example: Smith + maxLength: 50 + x-linode-cli-display: 2 + phone: + type: string + description: | + The phone number associated with this Account. + example: 215-555-1212 + maxLength: 32 + 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. + example: PA + maxLength: 24 + 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 (`""`). + example: ATU99999999 + maxLength: 25 + zip: + type: string + description: |- + The zip code of this Account's billing address. The following restrictions apply: + + - Can only contain ASCII letters, numbers, and hyphens (`-`). + - Must not contain more than 9 letter or number characters. + example: 19102-1234 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/put-account + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: update + x-linode-grant: read_write + x-original-op-id: updateAccount + x-original-op-title: Account Update + x-linode-cli-command: account + /account/availability: + x-akamai: + file-path: paths/account-availability.yaml + path-info: /account/availability + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-availability + summary: List available services + tags: + - Account availability + description: |- + Returns a paginated list of the services available to you, for all Linode regions. + + __Note__. Only authorized Users can run this operation. + + + --- + + + - __CLI__. + + ``` + linode-cli account get-availability + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli account get-availability + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + List of regions and the services available in each. + content: + application/json: + schema: + allOf: + - type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + Account Service Availability object + x-akamai: + file-path: schemas/account-availability.yaml + additionalProperties: false + properties: + available: + type: array + description: | + __Read-only__ A list of services _available_ to your account in the + `region`. + example: + - Linodes + - NodeBalancers + readOnly: true + items: + type: string + region: + type: string + description: | + __Read-only__ The Akamai cloud computing data center (region), represented + by a slug value. You can view a full list of regions + and their associated slugs with the [List regions](https://techdocs.akamai.com/linode-api/reference/get-regions) + operation. + example: us-east + readOnly: true + x-linode-cli-display: 1 + unavailable: + type: array + description: | + __Read-only__ A list of services _unavailable_ to your account in + the `region`. + example: + - Kubernetes + - Block Storage + readOnly: true + items: + type: string + x-linode-cli-display: 3 + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-availability + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: get-availability + x-linode-grant: read_only + x-original-op-id: getAvailability + x-original-op-title: Account Availability + x-linode-cli-command: account + /account/availability/{id}: + x-akamai: + file-path: paths/data-center.yaml + path-info: /account/availability/{id} + parameters: + - name: id + in: path + 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. + example: '{{id}}' + x-akamai: + file-path: parameters/id-path.yaml + required: true + schema: + type: string + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-account-availability + summary: Get a region's service availability + tags: + - Account + description: |- + View the available services for your account in a specific region. + + __Note__. Only authorized users can access this. + + + --- + + + - __CLI__. + + ``` + linode-cli account get-account-availability + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli account get-account-availability + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + The services available in the specified region. + content: + application/json: + schema: + type: object + description: | + Account Service Availability object + x-akamai: + file-path: schemas/account-availability.yaml + additionalProperties: false + properties: + available: + type: array + description: | + __Read-only__ A list of services _available_ to your account in the `region`. + example: + - Linodes + - NodeBalancers + readOnly: true + items: + type: string + region: + type: string + description: | + __Read-only__ The Akamai cloud computing data center (region), represented by a slug + value. You can view a full list of regions and their associated + slugs with the [List regions](https://techdocs.akamai.com/linode-api/reference/get-regions) + operation. + example: us-east + readOnly: true + x-linode-cli-display: 1 + unavailable: + type: array + description: | + __Read-only__ A list of services _unavailable_ to your account in the `region`. + example: + - Kubernetes + - Block Storage + readOnly: true + items: + type: string + x-linode-cli-display: 3 + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-account-availability + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: get-account-availability + x-linode-grant: read_only + x-original-op-id: getAccountAvailability + x-original-op-title: Region Service Availability + x-linode-cli-command: account + /account/betas: + x-akamai: + file-path: paths/account-betas.yaml + path-info: /account/betas + post: + servers: + - url: https://api.linode.com/v4 + operationId: post-beta-program + summary: Enroll in a Beta program + tags: + - Beta programs + description: |- + Enroll your Account in an active Beta Program. + + Only unrestricted Users can access this operation. + + To view active Beta Programs, run the [List beta programs](https://techdocs.akamai.com/linode-api/reference/get-beta-programs) operation. + + 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. + + + --- + + + - __CLI__. + + ``` + linode-cli betas enroll + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli betas enroll + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Updated information for the Managed MySQL Database. + required: true + content: + application/json: + schema: + type: object + description: | + The Beta Program ID to enroll in for your Account. + additionalProperties: false + required: + - id + properties: + id: + type: string + description: | + The unique identifier of the Beta Program. + example: '{{id}}' + x-linode-cli-display: 1 + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Enrollment request successful. + content: + application/json: + schema: + type: object + x-akamai: + file-path: schemas/added-empty-obj.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-beta-program + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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 + x-linode-cli-action: enroll + x-linode-grant: unrestricted only + x-original-op-id: enrollBetaProgram + x-original-op-title: Beta Program Enroll + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-enrolled-beta-programs + summary: List enrolled Beta programs + tags: + - Beta programs + description: |- + Display all enrolled Beta Programs for your Account. Includes inactive as well as active Beta Programs. + + Only unrestricted Users can access this operation. + + + --- + + + - __CLI__. + + ``` + linode-cli betas enrolled + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli betas enrolled + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns a paginated list of all enrolled Beta Program objects for the Account. + content: + application/json: + schema: + allOf: + - type: object + description: | + An envelope for paginated response. When accessing a collection through a GET endpoint, + the results are wrapped in this envelope which includes metadata + about those results. Results are presented within a `data` array. + See [Pagination](https://techdocs.akamai.com/linode-api/reference/pagination) + for more information. + x-akamai: + file-path: schemas/pagination-envelope.yaml + additionalProperties: false + properties: + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + - type: object + properties: + data: + type: array + items: + type: object + description: | + An object representing an enrolled Beta Program for the Account. + x-akamai: + file-path: schemas/beta-program-enrolled.yaml + additionalProperties: false + properties: + id: + type: string + description: | + The unique identifier of the Beta Program. + example: example_open + x-linode-cli-display: 1 + description: + type: string + description: | + __Read-only__ Additional details regarding the Beta Program. + example: This is an open public beta for an example feature. + nullable: true + readOnly: true + x-linode-cli-display: 3 + ended: + type: string + description: |- + __Read-only__ The date-time that the Beta Program ended. + + `null` indicates that the Beta Program is ongoing. + example: null + nullable: true + readOnly: true + format: date-time + x-linode-cli-display: 5 + x-linode-filterable: true + enrolled: + type: string + description: | + __Read-only__ The date-time of Account enrollment to the Beta Program. + example: '2023-09-11T00:00:00' + readOnly: true + format: date-time + x-linode-cli-display: 6 + x-linode-filterable: true + label: + type: string + description: | + __Read-only__ The name of the Beta Program. + example: Example Open Beta + readOnly: true + x-linode-cli-display: 2 + x-linode-filterable: true + started: + type: string + description: | + __Read-only__ The start date-time of the Beta Program. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-enrolled-beta-programs + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: enrolled + x-linode-grant: unrestricted only + x-original-op-id: getEnrolledBetaPrograms + x-original-op-title: Enrolled Beta Programs List + x-linode-cli-command: betas + /account/betas/{betaId}: + x-akamai: + file-path: paths/account-beta.yaml + path-info: /account/betas/{betaId} + parameters: + - name: betaId + in: path + description: | + The ID of the Beta Program. + example: '{{betaId}}' + x-akamai: + file-path: parameters/beta-id.yaml + required: true + schema: + type: string + get: + servers: + - url: https://api.linode.com/v4 + operationId: get-enrolled-beta-program + summary: Get an enrolled Beta program + tags: + - Beta programs + description: |- + Display an enrolled Beta Program for your Account. The Beta Program may be inactive. + + Only unrestricted Users can access this operation. + + + --- + + + - __CLI__. + + ``` + linode-cli betas enrolled-view + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli betas enrolled-view + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns an enrolled Beta Program object for the Account. + content: + application/json: + schema: + type: object + description: | + An object representing an enrolled Beta Program for the Account. + x-akamai: + file-path: schemas/beta-program-enrolled.yaml + additionalProperties: false + properties: + id: + type: string + description: | + The unique identifier of the Beta Program. + example: example_open + x-linode-cli-display: 1 + description: + type: string + description: | + __Read-only__ Additional details regarding the Beta Program. + example: This is an open public beta for an example feature. + nullable: true + readOnly: true + x-linode-cli-display: 3 + ended: + type: string + description: |- + __Read-only__ The date-time that the Beta Program ended. + + `null` indicates that the Beta Program is ongoing. + example: null + nullable: true + readOnly: true + format: date-time + x-linode-cli-display: 5 + x-linode-filterable: true + enrolled: + type: string + description: | + __Read-only__ The date-time of Account enrollment to the Beta Program. + example: '2023-09-11T00:00:00' + readOnly: true + format: date-time + x-linode-cli-display: 6 + x-linode-filterable: true + label: + type: string + description: | + __Read-only__ The name of the Beta Program. + example: Example Open Beta + readOnly: true + x-linode-cli-display: 2 + x-linode-filterable: true + started: + type: string + description: | + __Read-only__ The start date-time of the Beta Program. + example: '2023-07-11T00:00:00' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-enrolled-beta-program + security: + - personalAccessToken: [] + - oauth: + - account:read_only + 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 + x-linode-cli-action: enrolled-view + x-linode-grant: unrestricted only + x-original-op-id: getEnrolledBetaProgram + x-original-op-title: Enrolled Beta Program View + x-linode-cli-command: betas + /account/cancel: + x-akamai: + file-path: paths/account-cancel.yaml + path-info: /account/cancel + post: + operationId: post-cancel-account + summary: Cancel your account + tags: + - Account + 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 operation can only be accessed by account users with _unrestricted_ access. + + __Parent and child accounts__ In a [parent and child account](https://www.linode.com/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. + + + --- + + + - __CLI__. + + ``` + linode-cli account cancel + ``` + + [Learn more...](https://www.linode.com/docs/products/tools/cli/get-started/) + + - __OAuth__. + + ``` + account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: CLI + syntax: linode-cli account cancel + url: https://www.linode.com/docs/products/tools/cli/get-started/ + - title: OAuth + syntax: account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + description: | + Supply a comment stating the reason that you are cancelling your account. + required: true + content: + application/json: + schema: + additionalProperties: false + 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. + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Account canceled + content: + application/json: + schema: + type: object + example: + survey_link: https://alinktothesurvey.com + additionalProperties: false + properties: + survey_link: + type: string + description: | + A link to Linode's exit survey. + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + 409: + description: | + Could not charge the credit card on file + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + additionalProperties: false + 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. + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/post-cancel-account + security: + - personalAccessToken: [] + - oauth: + - account:read_write + 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" + x-linode-cli-action: cancel + x-linode-grant: read_write + x-original-op-id: cancelAccount + x-original-op-title: Account Cancel + x-linode-cli-command: account + /account/child-accounts: + x-akamai: + file-path: paths/child-accounts.yaml + path-info: /account/child-accounts + get: + operationId: get-child-accounts + summary: List child accounts + tags: + - Child accounts + 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](https://www.linode.com/docs/guides/parent-child-accounts/) for details on these accounts. + + __Note__. This operation can only be accessed by an unrestricted parent user, or restricted parent user with the `child_account_access` grant. + + + --- + + + - __OAuth__. + + ``` + child_account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: child_account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: + - name: page + in: query + description: | + The page of a collection to return. + example: '{{page}}' + x-akamai: + file-path: parameters/page-offset.yaml + required: false + schema: + type: integer + default: 1 + minimum: 1 + - name: page_size + in: query + description: | + The number of items to return per page. + example: '{{page_size}}' + x-akamai: + file-path: parameters/page-size.yaml + schema: + type: integer + default: 100 + minimum: 25 + maximum: 500 + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns child-level accounts. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + data: + type: array + items: + type: object + description: | + Child account object + x-akamai: + file-path: schemas/child-account.yaml + additionalProperties: false + properties: + active_since: + type: string + description: | + __Read-only__ The activation date and time for the child account. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + address_1: + type: string + description: | + First line of this child account's billing address. + example: 123 Main Street + maxLength: 64 + x-linode-filterable: true + address_2: + type: string + description: | + Second line of this child account's billing address, if applicable. + example: Suite A + maxLength: 64 + x-linode-filterable: true + balance: + type: number + description: | + __Read-only__ This child account's balance, in US dollars. + example: 200 + readOnly: true + x-linode-cli-display: 4 + balance_uninvoiced: + 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. + example: 145 + readOnly: true + x-linode-cli-display: 4 + billing_source: + type: string + 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. + example: external + readOnly: true + enum: + - external + capabilities: + type: array + description: | + __Read-only__ A list of the capabilities the child account supports. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + readOnly: true + items: + type: string + city: + type: string + description: | + The city for this child account's billing address. + example: San Diego + maxLength: 24 + x-linode-filterable: true + company: + type: string + description: | + '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.' + example: Acme + maxLength: 128 + x-linode-filterable: true + country: + type: string + description: | + The two-letter ISO 3166 country code for this child account's billing + address. + example: US + x-linode-filterable: true + credit_card: + type: object + description: | + __Read-only__ Information for the credit card you've assigned to this + child account. + additionalProperties: false + readOnly: true + properties: + expiry: + type: string + description: | + The expiration month and year of the credit card. + example: 11/2024 + last_four: + type: string + description: | + The last four digits of the credit card. + example: 1111 + email: + type: string + description: | + The email address of the owner of this child account. + example: john.smith@linode.com + maxLength: 128 + x-linode-cli-display: 3 + x-linode-filterable: true + euuid: + type: string + description: | + __Read-only__ An external, unique identifier that Akamai assigned to + the child account. + example: A1BC2DEF-34GH-567I-J890KLMN12O34P56 + readOnly: true + format: uuid + first_name: + type: string + description: | + 'The first name of the owner of this child account. It can''t include + any of these characters: `<` `>` `(` `)` `"` `=`.' + example: John + maxLength: 50 + x-linode-cli-display: 1 + x-linode-filterable: true + last_name: + type: string + description: | + 'The last name of the owner of this child account. It can''t include + any of these characters: `<` `>` `(` `)` `"` `=`.' + example: Smith + maxLength: 50 + x-linode-cli-display: 2 + x-linode-filterable: true + phone: + type: string + description: | + The phone number for the owner of this child account. + example: 858-555-1212 + maxLength: 32 + x-linode-filterable: true + state: + type: string + description: |- + 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. + + __Note:__ If this is a US military address, use state abbreviations (AA, AE, AP). + example: CA + maxLength: 24 + x-linode-filterable: true + tax_id: + type: string + 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 (`""`). + example: ATU99999999 + maxLength: 25 + zip: + type: string + description: |- + The zip code of this Account's billing address. The following restrictions apply: + + - Can only contain ASCII letters, numbers, and hyphens (`-`). + - Can't contain more than 9 letter or number characters. + example: 92111-1234 + x-linode-filterable: true + page: + type: integer + description: | + __Read-only__ The current [page](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + pages: + type: integer + description: | + __Read-only__ The total number of [pages](https://techdocs.akamai.com/linode-api/reference/pagination). + example: 1 + readOnly: true + results: + type: integer + description: | + __Read-only__ The total number of results. + example: 1 + readOnly: true + x-ref: ../schemas/added-tbd.yaml + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-child-accounts + security: + - personalAccessToken: [] + - oauth: + - child_account:read_only + 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 + x-linode-cli-action: + - list + - ls + x-linode-grant: child_account_access + x-original-op-id: getChildAccounts + x-original-op-title: Child Account List + x-linode-cli-command: child-account + /account/child-accounts/{euuid}: + x-akamai: + file-path: paths/child-account.yaml + path-info: /account/child-accounts/{euuid} + parameters: + - name: euuid + in: path + 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`. + example: '{{euuid}}' + x-akamai: + file-path: parameters/eeuid.yaml + required: true + schema: + type: string + get: + operationId: get-child-account + summary: Get a child account + tags: + - Child accounts + description: |- + View a specific child account based on its `euuid`. See [Parent and Child Accounts for Akamai Partners](https://www.linode.com/docs/guides/parent-child-accounts/) for details on these accounts. + + __Note__. This operation can only be accessed by an unrestricted user, or restricted user with the `child_account_access` grant. + + + --- + + + - __OAuth__. + + ``` + child_account:read_only + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: child_account:read_only + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Returns the child-level account for a specified `euuid`. + content: + application/json: + schema: + type: object + description: | + Child account object + x-akamai: + file-path: schemas/child-account.yaml + additionalProperties: false + properties: + active_since: + type: string + description: | + __Read-only__ The activation date and time for the child account. + example: '2018-01-01T00:01:01' + readOnly: true + format: date-time + address_1: + type: string + description: | + First line of this child account's billing address. + example: 123 Main Street + maxLength: 64 + x-linode-filterable: true + address_2: + type: string + description: | + Second line of this child account's billing address, if applicable. + example: Suite A + maxLength: 64 + x-linode-filterable: true + balance: + type: number + description: | + __Read-only__ This child account's balance, in US dollars. + example: 200 + readOnly: true + x-linode-cli-display: 4 + balance_uninvoiced: + 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. + example: 145 + readOnly: true + x-linode-cli-display: 4 + billing_source: + type: string + 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. + example: external + readOnly: true + enum: + - external + capabilities: + type: array + description: | + __Read-only__ A list of the capabilities the child account supports. + example: + - Linodes + - NodeBalancers + - Block Storage + - Object Storage + readOnly: true + items: + type: string + city: + type: string + description: | + The city for this child account's billing address. + example: San Diego + maxLength: 24 + x-linode-filterable: true + company: + type: string + description: | + '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.' + example: Acme + maxLength: 128 + x-linode-filterable: true + country: + type: string + description: | + The two-letter ISO 3166 country code for this child account's billing address. + example: US + x-linode-filterable: true + credit_card: + type: object + description: | + __Read-only__ Information for the credit card you've assigned to this child account. + additionalProperties: false + readOnly: true + properties: + expiry: + type: string + description: | + The expiration month and year of the credit card. + example: 11/2024 + last_four: + type: string + description: | + The last four digits of the credit card. + example: 1111 + email: + type: string + description: | + The email address of the owner of this child account. + example: john.smith@linode.com + maxLength: 128 + x-linode-cli-display: 3 + x-linode-filterable: true + euuid: + type: string + description: | + __Read-only__ An external, unique identifier that Akamai assigned to the child account. + example: A1BC2DEF-34GH-567I-J890KLMN12O34P56 + readOnly: true + format: uuid + first_name: + type: string + description: | + 'The first name of the owner of this child account. It can''t include any of these + characters: `<` `>` `(` `)` `"` `=`.' + example: John + maxLength: 50 + x-linode-cli-display: 1 + x-linode-filterable: true + last_name: + type: string + description: | + 'The last name of the owner of this child account. It can''t include any of these + characters: `<` `>` `(` `)` `"` `=`.' + example: Smith + maxLength: 50 + x-linode-cli-display: 2 + x-linode-filterable: true + phone: + type: string + description: | + The phone number for the owner of this child account. + example: 858-555-1212 + maxLength: 32 + x-linode-filterable: true + state: + type: string + description: |- + 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. + + __Note:__ If this is a US military address, use state abbreviations (AA, AE, AP). + example: CA + maxLength: 24 + x-linode-filterable: true + tax_id: + type: string + 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 (`""`). + example: ATU99999999 + maxLength: 25 + zip: + type: string + description: |- + The zip code of this Account's billing address. The following restrictions apply: + + - Can only contain ASCII letters, numbers, and hyphens (`-`). + - Can't contain more than 9 letter or number characters. + example: 92111-1234 + x-linode-filterable: true + x-example: + x-ref: ../examples/tbd.json + externalDocs: + description: | + See documentation for this operation in Akamai's Linode API + url: https://techdocs.akamai.com/linode-api/reference/get-child-account + security: + - personalAccessToken: [] + - oauth: + - child_account:read_only + 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 + x-linode-cli-action: + - view + x-linode-grant: child_account_access + x-original-op-id: viewChildAccount + x-original-op-title: Child Account View + x-linode-cli-command: child-account + /account/child-accounts/{euuid}/token: + x-akamai: + file-path: paths/child-account-token.yaml + path-info: /account/child-accounts/{euuid}/token + parameters: + - name: euuid + in: path + 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`. + example: '{{euuid}}' + x-akamai: + file-path: parameters/eeuid.yaml + required: true + schema: + type: string + post: + operationId: post-child-account-token + summary: Create a proxy user token + tags: + - Child accounts + 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 run [List a user's grants](https://techdocs.akamai.com/linode-api/reference/get-user-grants) on a parent account user to check its `child_account_access` setting. To add this access, you can [update](https://techdocs.akamai.com/linode-api/reference/put-user-grants) 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](https://techdocs.akamai.com/linode-api/reference/get-child-accounts) 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. + + + --- + + + - __OAuth__. + + ``` + child_account:read_write + ``` + + [Learn more...](https://techdocs.akamai.com/linode-api/reference/oauth) + x-akamai: + tabs: + - title: OAuth + syntax: child_account:read_write + url: https://techdocs.akamai.com/linode-api/reference/oauth + parameters: [] + requestBody: + content: + application/json: {} + responses: + default: + description: | + Error + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + errors: + type: array + items: + type: object + description: | + An object for describing a single error that occurred during the processing of a request. + x-akamai: + file-path: schemas/error-object.yaml + additionalProperties: false + properties: + field: + type: string + description: | + The field in the request that caused this error. This may be a path, + separated by periods in the case of nested fields. In + some cases this may come back as "null" if the error is + not specific to any single element of the request. + example: fieldname + reason: + type: string + description: | + What happened to cause this error. In most cases, this can be fixed + immediately by changing the data you sent in the request, + but in some cases you will be instructed to [Open a support + ticket](https://techdocs.akamai.com/linode-api/reference/post-ticket) + or perform some other action before you can complete the + request successfully. + example: fieldname must be a valid value + 200: + description: | + Token created successfully. + content: + application/json: + schema: + type: object + 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. + x-akamai: + file-path: schemas/proxy-user-token.yaml + additionalProperties: false + properties: + id: + type: integer + description: | + __Read-only__ The proxy user token's unique ID, which can be used to revoke it. + example: 918 + readOnly: true + x-linode-cli-display: 1 + created: + type: string + description: | + __Read-only__ The date and time this token was created. + example: '2024-05-01T00:01:01' + readOnly: true + format: date-time + x-linode-cli-display: 4 + x-linode-filterable: true + expiry: + type: string + description: | + __Read-only__ When this token expires. This is default set to 15 minutes from the + time of creation. Proxy user tokens can't be renewed. After + this time, Akamai revokes the token and you need to generate + a new one. + example: '2024-05-01T00:16:01' + readOnly: true + format: date-time + x-linode-cli-display: 6 + label: + type: string + description: | + The name of the token. The API automatically sets this to `__