linode Account API

openapi: 3.2.0
info:
  title: Linode API v4 Account API
  description: The Linode API v4 provides programmatic access to the full range of Akamai Connected Cloud (formerly Linode) products and services.
  version: 4.189.0
  contact:
    name: Linode Support
    url: https://www.linode.com/support/
  termsOfService: https://www.linode.com/legal-tos/
servers:
- url: https://api.linode.com/v4
  description: Production Server
security:
- personalAccessToken: []
- oauth: []
tags:
- name: Account
  description: Manage your account settings, users, billing information, OAuth clients, service transfers, and payment methods.
paths:
  /account:
    get:
      operationId: getAccount
      summary: Get account info
      description: Returns the contact and billing information related to your account, including company name, address, phone number, and current balance.
      tags:
      - Account
      responses:
        '200':
          description: Account information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized - invalid or missing authentication
    put:
      operationId: updateAccount
      summary: Update account info
      description: Updates contact and billing information on your account.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        '200':
          description: Account information updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing authentication
  /account/users:
    get:
      operationId: getUsers
      summary: List users
      description: Returns a paginated list of users on your account, including their usernames, email addresses, and restricted status.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/pageSizeParam'
      responses:
        '200':
          description: Users retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedUserList'
        '401':
          description: Unauthorized - invalid or missing authentication
    post:
      operationId: createUser
      summary: Create a user
      description: Creates a new user on your account. The new user will receive an email to set their password.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing authentication
  /account/users/{username}:
    get:
      operationId: getUser
      summary: Get a user
      description: Returns information about a single user on your account.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/usernameParam'
      responses:
        '200':
          description: User retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized - invalid or missing authentication
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: Update a user
      description: Updates information about a user on your account, including their username, email, and restricted status.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/usernameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing authentication
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Delete a user
      description: Deletes a user from your account. The deleted user will lose access to the account immediately.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/usernameParam'
      responses:
        '200':
          description: User deleted successfully
        '401':
          description: Unauthorized - invalid or missing authentication
        '404':
          description: User not found
  /account/events:
    get:
      operationId: getEvents
      summary: List events
      description: Returns a paginated list of events on your account, ordered by creation date descending. Events record actions taken on your account such as instance creation, deletion, and configuration changes.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/pageSizeParam'
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEventList'
        '401':
          description: Unauthorized - invalid or missing authentication
  /account/events/{eventId}:
    get:
      operationId: getEvent
      summary: Get an event
      description: Returns a single event object by its ID.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/eventIdParam'
      responses:
        '200':
          description: Event retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          description: Unauthorized - invalid or missing authentication
        '404':
          description: Event not found
  /account/invoices:
    get:
      operationId: getInvoices
      summary: List invoices
      description: Returns a paginated list of invoices on your account.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/pageSizeParam'
      responses:
        '200':
          description: Invoices retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvoiceList'
        '401':
          description: Unauthorized - invalid or missing authentication
  /account/payments:
    get:
      operationId: getPayments
      summary: List payments
      description: Returns a paginated list of payments made on your account.
      tags:
      - Account
      parameters:
      - $ref: '#/components/parameters/pageParam'
      - $ref: '#/components/parameters/pageSizeParam'
      responses:
        '200':
          description: Payments retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPaymentList'
        '401':
          description: Unauthorized - invalid or missing authentication
    post:
      operationId: createPayment
      summary: Make a payment
      description: Makes a payment on your account using the US Dollar amount provided.
      tags:
      - Account
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
      responses:
        '200':
          description: Payment made successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Bad request - invalid parameters
        '401':
          description: Unauthorized - invalid or missing authentication
components:
  schemas:
    Event:
      type: object
      properties:
        id:
          type: integer
          description: The unique ID of the event.
        action:
          type: string
          description: The action that caused this event.
          enum:
          - linode_boot
          - linode_create
          - linode_delete
          - linode_reboot
          - linode_rebuild
          - linode_resize
          - linode_shutdown
          - linode_update
          - disk_create
          - disk_delete
          - disk_resize
          - domain_create
          - domain_delete
          - domain_update
          - domain_record_create
          - domain_record_delete
          - domain_record_update
          - firewall_create
          - firewall_delete
          - firewall_update
          - lke_cluster_create
          - lke_cluster_delete
          - lke_cluster_update
          - nodebalancer_create
          - nodebalancer_delete
          - nodebalancer_update
          - volume_create
          - volume_delete
          - volume_attach
          - volume_detach
        created:
          type: string
          format: date-time
          description: When this event was created.
        entity:
          type: object
          properties:
            id:
              type: integer
              description: The ID of the entity related to this event.
            label:
              type: string
              description: The label of the entity.
            type:
              type: string
              description: The type of entity.
            url:
              type: string
              description: The URL of the entity in the API.
          description: The entity that this event is related to.
        status:
          type: string
          enum:
          - failed
          - finished
          - notification
          - scheduled
          - started
          description: The current status of the event.
        username:
          type: string
          description: The username of the user who initiated this event.
        percent_complete:
          type: integer
          minimum: 0
          maximum: 100
          description: The percentage of completion for the event.
        seen:
          type: boolean
          description: Whether the event has been seen by the user.
        read:
          type: boolean
          description: Whether the event has been read by the user.
    PaginatedEventList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Event'
    Payment:
      type: object
      properties:
        id:
          type: integer
          description: The unique ID of this payment.
        date:
          type: string
          format: date-time
          description: The date this payment was made.
        usd:
          type: number
          description: The amount in US dollars.
    PaginatedUserList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/User'
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: The current page number.
        pages:
          type: integer
          description: The total number of pages.
        results:
          type: integer
          description: The total number of results.
    Account:
      type: object
      properties:
        company:
          type: string
          description: The company name associated with this account.
        email:
          type: string
          format: email
          description: The email address associated with this account.
        first_name:
          type: string
          description: The first name of the account holder.
        last_name:
          type: string
          description: The last name of the account holder.
        address_1:
          type: string
          description: The first line of the account's address.
        address_2:
          type: string
          description: The second line of the account's address.
        city:
          type: string
          description: The city of the account's address.
        state:
          type: string
          description: The state or province of the account's address.
        zip:
          type: string
          description: The postal code of the account's address.
        country:
          type: string
          description: The two-letter ISO 3166-1 country code.
        phone:
          type: string
          description: The phone number for the account.
        balance:
          type: number
          format: float
          description: The current account balance in US dollars.
        active_since:
          type: string
          format: date-time
          description: The date and time the account was activated.
        capabilities:
          type: array
          items:
            type: string
          description: A list of capabilities enabled on this account.
    UserRequest:
      type: object
      required:
      - username
      - email
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 32
          description: The user's username.
        email:
          type: string
          format: email
          description: The user's email address.
        restricted:
          type: boolean
          description: Whether the user should have restricted access.
    Invoice:
      type: object
      properties:
        id:
          type: integer
          description: The unique ID of this invoice.
        date:
          type: string
          format: date-time
          description: The date of this invoice.
        label:
          type: string
          description: The label for this invoice.
        subtotal:
          type: number
          description: The subtotal amount.
        tax:
          type: number
          description: The tax amount.
        total:
          type: number
          description: The total amount.
    PaymentRequest:
      type: object
      required:
      - usd
      properties:
        usd:
          type: number
          minimum: 5
          maximum: 10000
          description: The payment amount in US dollars.
    PaginatedInvoiceList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Invoice'
    PaginatedPaymentList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Payment'
    User:
      type: object
      properties:
        username:
          type: string
          description: The user's username.
        email:
          type: string
          format: email
          description: The user's email address.
        restricted:
          type: boolean
          description: Whether the user has restricted access to account resources.
        ssh_keys:
          type: array
          items:
            type: string
          description: A list of SSH key labels associated with the user.
        tfa_enabled:
          type: boolean
          description: Whether two-factor authentication is enabled.
  parameters:
    usernameParam:
      name: username
      in: path
      required: true
      schema:
        type: string
      description: The username of the user.
    pageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
      description: The page number to return.
    eventIdParam:
      name: eventId
      in: path
      required: true
      schema:
        type: integer
      description: The ID of the event.
    pageSizeParam:
      name: page_size
      in: query
      schema:
        type: integer
        minimum: 25
        maximum: 500
        default: 100
      description: The number of items per page.
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: bearer
      description: A personal access token generated from the Linode Cloud Manager that grants access to the API based on the token's scopes.
    oauth:
      type: oauth2
      description: OAuth 2.0 authentication for third-party applications.
      flows:
        authorizationCode:
          authorizationUrl: https://login.linode.com/oauth/authorize
          tokenUrl: https://login.linode.com/oauth/token
          scopes:
            account:read_only: Read access to account information
            account:read_write: Read and write access to account information
            domains:read_only: Read access to domains
            domains:read_write: Read and write access to domains
            events:read_only: Read access to events
            events:read_write: Read and write access to events
            firewall:read_only: Read access to firewalls
            firewall:read_write: Read and write access to firewalls
            images:read_only: Read access to images
            images:read_write: Read and write access to images
            ips:read_only: Read access to IP addresses
            ips:read_write: Read and write access to IP addresses
            linodes:read_only: Read access to Linodes
            linodes:read_write: Read and write access to Linodes
            lke:read_only: Read access to LKE
            lke:read_write: Read and write access to LKE
            longview:read_only: Read access to Longview
            longview:read_write: Read and write access to Longview
            nodebalancers:read_only: Read access to NodeBalancers
            nodebalancers:read_write: Read and write access to NodeBalancers
            object_storage:read_only: Read access to Object Storage
            object_storage:read_write: Read and write access to Object Storage
            stackscripts:read_only: Read access to StackScripts
            stackscripts:read_write: Read and write access to StackScripts
            volumes:read_only: Read access to Volumes
            volumes:read_write: Read and write access to Volumes
            vpc:read_only: Read access to VPCs
            vpc:read_write: Read and write access to VPCs
externalDocs:
  description: Linode API v4 Documentation
  url: https://techdocs.akamai.com/linode-api/reference/api