Elastic Stack (ELK Stack) License API

openapi: 3.2.0
info:
  title: Elasticsearch Request & Response Specification License API
  license:
    name: Apache 2.0
    url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
  version: ''
tags:
- name: license
paths:
  /_license:
    get:
      tags:
      - license
      summary: Get license information
      description: 'Get information about your Elastic license including its type, its status, when it was issued, and when it expires.


        >info

        > If the master node is generating a new cluster state, the get license API may return a `404 Not Found` response.

        > If you receive an unexpected 404 response after cluster startup, wait a short period and retry the request.'
      operationId: license-get
      parameters:
      - in: query
        name: accept_enterprise
        description: 'If `true`, this parameter returns enterprise for Enterprise license types. If `false`, this parameter returns platinum for both platinum and enterprise license types. This behavior is maintained for backwards compatibility.

          This parameter is deprecated and will always be set to true in 8.x.'
        deprecated: true
        schema:
          default: true
          type: boolean
        style: form
      - in: query
        name: local
        description: 'Specifies whether to retrieve local information.

          From 9.2 onwards the default value is `true`, which means the information is retrieved from the responding node.

          In earlier versions the default is `false`, which means the information is retrieved from the elected master node.'
        deprecated: false
        schema:
          default: true
          type: boolean
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  license:
                    allOf:
                    - $ref: '#/components/schemas/license.get.LicenseInformation'
                required:
                - license
              examples:
                GetLicenseResponseExample1:
                  description: A successful response from `GET /_license`.
                  value: "{\n  \"license\" : {\n    \"status\" : \"active\",\n    \"uid\" : \"cbff45e7-c553-41f7-ae4f-9205eabd80xx\",\n    \"type\" : \"trial\",\n    \"issue_date\" : \"2018-10-20T22:05:12.332Z\",\n    \"issue_date_in_millis\" : 1540073112332,\n    \"expiry_date\" : \"2018-11-19T22:05:12.332Z\",\n    \"expiry_date_in_millis\" : 1542665112332,\n    \"max_nodes\" : 1000,\n    \"max_resource_units\" : null,\n    \"issued_to\" : \"test\",\n    \"issuer\" : \"elasticsearch\",\n    \"start_date_in_millis\" : -1\n  }\n}"
      x-state: Generally available
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    put:
      tags:
      - license
      summary: Update the license
      description: 'You can update your license at runtime without shutting down your nodes.

        License updates take effect immediately.

        If the license you are installing does not support all of the features that were available with your previous license, however, you are notified in the response.

        You must then re-submit the API request with the acknowledge parameter set to true.


        NOTE: If Elasticsearch security features are enabled and you are installing a gold or higher license, you must enable TLS on the transport networking layer before you install the license.

        If the operator privileges feature is enabled, only operator users can use this API.


        ## Required authorization


        * Cluster privileges: `manage`

        '
      operationId: license-post
      parameters:
      - $ref: '#/components/parameters/license.post-acknowledge'
      - $ref: '#/components/parameters/license.post-master_timeout'
      - $ref: '#/components/parameters/license.post-timeout'
      requestBody:
        $ref: '#/components/requestBodies/license.post'
      responses:
        '200':
          $ref: '#/components/responses/license.post-200'
      x-state: Generally available
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    post:
      tags:
      - license
      summary: Update the license
      description: 'You can update your license at runtime without shutting down your nodes.

        License updates take effect immediately.

        If the license you are installing does not support all of the features that were available with your previous license, however, you are notified in the response.

        You must then re-submit the API request with the acknowledge parameter set to true.


        NOTE: If Elasticsearch security features are enabled and you are installing a gold or higher license, you must enable TLS on the transport networking layer before you install the license.

        If the operator privileges feature is enabled, only operator users can use this API.


        ## Required authorization


        * Cluster privileges: `manage`

        '
      operationId: license-post-1
      parameters:
      - $ref: '#/components/parameters/license.post-acknowledge'
      - $ref: '#/components/parameters/license.post-master_timeout'
      - $ref: '#/components/parameters/license.post-timeout'
      requestBody:
        $ref: '#/components/requestBodies/license.post'
      responses:
        '200':
          $ref: '#/components/responses/license.post-200'
      x-state: Generally available
      x-metaTags:
      - content: Elasticsearch
        name: product_name
    delete:
      tags:
      - license
      summary: Delete the license
      description: 'When the license expires, your subscription level reverts to Basic.


        If the operator privileges feature is enabled, only operator users can use this API.


        ## Required authorization


        * Cluster privileges: `manage`

        '
      externalDocs:
        description: About managing your license
        url: https://www.elastic.co/docs/deploy-manage/license/manage-your-license-in-self-managed-cluster
        x-previousVersionUrl: https://www.elastic.co/guide/en/elasticsearch/reference/8.19/delete-license.html
      operationId: license-delete
      parameters:
      - in: query
        name: master_timeout
        description: The period to wait for a connection to the master node.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      - in: query
        name: timeout
        description: The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
      x-state: Generally available
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_license/basic_status:
    get:
      tags:
      - license
      summary: Get the basic license status
      description: '


        ## Required authorization


        * Cluster privileges: `monitor`

        '
      operationId: license-get-basic-status
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  eligible_to_start_basic:
                    type: boolean
                required:
                - eligible_to_start_basic
              examples:
                GetBasicLicenseStatusResponseExample1:
                  description: A successful response from `GET /_license/basic_status`.
                  value: "{\n  \"eligible_to_start_basic\": true\n}"
      x-state: Generally available; Added in 6.3.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_license/trial_status:
    get:
      tags:
      - license
      summary: Get the trial status
      description: '


        ## Required authorization


        * Cluster privileges: `monitor`

        '
      operationId: license-get-trial-status
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  eligible_to_start_trial:
                    type: boolean
                required:
                - eligible_to_start_trial
              examples:
                GetTrialLicenseStatusResponseExample1:
                  description: A successful response from `GET /_license/trial_status`.
                  value: "{\n  \"eligible_to_start_trial\": true\n}"
      x-state: Generally available; Added in 6.1.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_license/start_basic:
    post:
      tags:
      - license
      summary: Start a basic license
      description: 'Start an indefinite basic license, which gives access to all the basic features.


        NOTE: In order to start a basic license, you must not currently have a basic license.


        If the basic license does not support all of the features that are available with your current license, however, you are notified in the response.

        You must then re-submit the API request with the `acknowledge` parameter set to `true`.


        To check the status of your basic license, use the get basic license API.


        ## Required authorization


        * Cluster privileges: `manage`

        '
      operationId: license-post-start-basic
      parameters:
      - in: query
        name: acknowledge
        description: To start a basic license, you must accept the acknowledge messages and set this parameter to `true`.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      - in: query
        name: master_timeout
        description: Period to wait for a connection to the master node.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      - in: query
        name: timeout
        description: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  acknowledged:
                    type: boolean
                  basic_was_started:
                    type: boolean
                  error_message:
                    type: string
                  type:
                    allOf:
                    - $ref: '#/components/schemas/license._types.LicenseType'
                  acknowledge:
                    type: object
                    additionalProperties:
                      oneOf:
                      - type: string
                      - type: array
                        items:
                          type: string
                required:
                - acknowledged
                - basic_was_started
              examples:
                StartBasicLicenseResponseExample1:
                  description: A successful response from `POST /_license/start_basic?acknowledge=true`. If you currently have a license with more features than a basic license and you start a basic license, you must pass the acknowledge parameter.
                  value: "{\n  \"basic_was_started\": true,\n  \"acknowledged\": true\n}"
      x-state: Generally available; Added in 6.3.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
  /_license/start_trial:
    post:
      tags:
      - license
      summary: Start a trial
      description: 'Start a 30-day trial, which gives access to all subscription features.


        NOTE: You are allowed to start a trial only if your cluster has not already activated a trial for the current major product version.

        For example, if you have already activated a trial for v8.0, you cannot start a new trial until v9.0. You can, however, request an extended trial at https://www.elastic.co/trialextension.


        To check the status of your trial, use the get trial status API.


        ## Required authorization


        * Cluster privileges: `manage`

        '
      operationId: license-post-start-trial
      parameters:
      - in: query
        name: acknowledge
        description: To start a trial, you must accept the acknowledge messages and set this parameter to `true`.
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      - in: query
        name: type
        description: The type of trial license to generate
        deprecated: false
        schema:
          default: trial
          type: string
        style: form
      - in: query
        name: master_timeout
        description: Period to wait for a connection to the master node.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  acknowledged:
                    type: boolean
                  error_message:
                    type: string
                  trial_was_started:
                    type: boolean
                  type:
                    allOf:
                    - $ref: '#/components/schemas/license._types.LicenseType'
                required:
                - acknowledged
                - trial_was_started
              examples:
                StartTrialLicenseResponseExample1:
                  description: A successful response from `POST /_license/start_trial?acknowledge=true`.
                  value: "{\n  \"trial_was_started\": true,\n  \"acknowledged\": true\n}"
      x-state: Generally available; Added in 6.1.0
      x-metaTags:
      - content: Elasticsearch
        name: product_name
components:
  schemas:
    _types.DateTime:
      description: 'A date and time, either as a string whose format can depend on the context (defaulting to ISO 8601), or a

        number of milliseconds since the Epoch. Elasticsearch accepts both as input, but will generally output a string

        representation.'
      oneOf:
      - type: string
      - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
    license.post.Acknowledgement:
      type: object
      properties:
        license:
          type: array
          items:
            type: string
        message:
          type: string
      required:
      - license
      - message
    license._types.License:
      type: object
      properties:
        expiry_date_in_millis:
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
        issue_date_in_millis:
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
        start_date_in_millis:
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
        issued_to:
          type: string
        issuer:
          type: string
        max_nodes:
          oneOf:
          - type: number
          - type:
            - string
            - 'null'
        max_resource_units:
          type: number
        signature:
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/license._types.LicenseType'
        uid:
          type: string
      required:
      - expiry_date_in_millis
      - issue_date_in_millis
      - issued_to
      - issuer
      - signature
      - type
      - uid
    _types.AcknowledgedResponseBase:
      type: object
      properties:
        acknowledged:
          description: For a successful response, this value is always true. On failure, an exception is returned instead.
          type: boolean
      required:
      - acknowledged
    _types.EpochTimeUnitMillis:
      allOf:
      - $ref: '#/components/schemas/_types.UnitMillis'
    license.get.LicenseInformation:
      type: object
      properties:
        expiry_date:
          description: The date and time the license expires in ISO 8601 format.
          allOf:
          - $ref: '#/components/schemas/_types.DateTime'
        expiry_date_in_millis:
          description: The date and time the license expires in milliseconds since the Unix epoch.
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
        issue_date:
          description: The date and time the license was issued in ISO 8601 format.
          allOf:
          - $ref: '#/components/schemas/_types.DateTime'
        issue_date_in_millis:
          description: The date and time the license was issued in milliseconds since the Unix epoch.
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
        issued_to:
          description: The name of the customer or organization that received the license.
          type: string
        issuer:
          description: The name of the organization that issued the license.
          type: string
        max_nodes:
          description: The maximum number of nodes the license allows.
          oneOf:
          - type: number
          - type:
            - string
            - 'null'
        max_resource_units:
          description: The maximum number of resource units the license allows (for enterprise licenses only).
          oneOf:
          - type: number
          - type:
            - string
            - 'null'
        status:
          description: The status of the license. For example,active, valid, invalid, or expired.
          allOf:
          - $ref: '#/components/schemas/license._types.LicenseStatus'
        type:
          description: The type of the license. For example, trial, basic, gold, platinum, or enterprise.
          allOf:
          - $ref: '#/components/schemas/license._types.LicenseType'
        uid:
          description: The unique identifier of the license.
          allOf:
          - $ref: '#/components/schemas/_types.Uuid'
        start_date_in_millis:
          description: The date and time the license was started in milliseconds since the Unix epoch.
          allOf:
          - $ref: '#/components/schemas/_types.EpochTimeUnitMillis'
      required:
      - issue_date
      - issue_date_in_millis
      - issued_to
      - issuer
      - max_nodes
      - status
      - type
      - uid
      - start_date_in_millis
    _types.Duration:
      externalDocs:
        url: https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units
      description: 'A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and

        `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.'
      oneOf:
      - type: string
      - type: string
        enum:
        - '-1'
      - type: string
        enum:
        - '0'
    license._types.LicenseType:
      type: string
      enum:
      - missing
      - trial
      - basic
      - standard
      - dev
      - silver
      - gold
      - platinum
      - enterprise
    _types.UnitMillis:
      description: Time unit for milliseconds
      type: number
    license._types.LicenseStatus:
      type: string
      enum:
      - active
      - valid
      - invalid
      - expired
    _types.Uuid:
      type: string
  requestBodies:
    license.post:
      content:
        application/json:
          schema:
            type: object
            properties:
              license:
                allOf:
                - $ref: '#/components/schemas/license._types.License'
              licenses:
                description: A sequence of one or more JSON documents containing the license information.
                type: array
                items:
                  $ref: '#/components/schemas/license._types.License'
          examples:
            PostLicenseRequestExample1:
              description: 'Run `PUT _license` to update to a basic license. NOTE: These values are invalid; you must substitute the appropriate contents from your license file.

                '
              value: "{\n  \"licenses\": [\n    {\n      \"uid\":\"893361dc-9749-4997-93cb-802e3d7fa4xx\",\n      \"type\":\"basic\",\n      \"issue_date_in_millis\":1411948800000,\n      \"expiry_date_in_millis\":1914278399999,\n      \"max_nodes\":1,\n      \"issued_to\":\"issuedTo\",\n      \"issuer\":\"issuer\",\n      \"signature\":\"xx\"\n    }\n    ]\n}"
  parameters:
    license.post-timeout:
      in: query
      name: timeout
      description: The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
      deprecated: false
      schema:
        default: 30s
        allOf:
        - $ref: '#/components/schemas/_types.Duration'
      style: form
    license.post-acknowledge:
      in: query
      name: acknowledge
      description: 'To update a license, you must accept the acknowledge messages and set this parameter to `true`.

        In particular, if you are upgrading or downgrading a license, you must acknowlege the feature changes.'
      deprecated: false
      schema:
        default: false
        type: boolean
      style: form
    license.post-master_timeout:
      in: query
      name: master_timeout
      description: The period to wait for a connection to the master node.
      deprecated: false
      schema:
        default: 30s
        allOf:
        - $ref: '#/components/schemas/_types.Duration'
      style: form
  responses:
    license.post-200:
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              acknowledge:
                allOf:
                - $ref: '#/components/schemas/license.post.Acknowledgement'
              acknowledged:
                type: boolean
              license_status:
                allOf:
                - $ref: '#/components/schemas/license._types.LicenseStatus'
            required:
            - acknowledged
            - license_status
          examples:
            PostLicenseResponseExample1:
              description: If you update to a basic license and you previously had a license with more features, you receive this type of response. You must re-submit the API request and set the `acknowledge` parameter to `true`.
              value: "{\n  \"acknowledged\": false,\n  \"license_status\": \"valid\",\n  \"acknowledge\": {\n    \"message\": \"\\\"\\\"\\\"This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the \\\"acknowledge=true\\\" parameter:\\\"\\\"\\\"\",\n    \"watcher\": [\n      \"Watcher will be disabled\"\n    ],\n    \"logstash\": [\n      \"Logstash will no longer poll for centrally-managed pipelines\"\n    ],\n    \"security\": [\n      \"The following X-Pack security functionality will be disabled ...\"\n    ]\n  }\n}"