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}"