Upsert links library item

Base URL: https://{kibana_url}

PUT /api/links/{id}

Auth

Replaces the full state of a links library item. Partial updates are not supported. To make incremental changes, retrieve the item first, modify the fields you need, then send the complete object back.

If no item exists with the specified ID, a new one is created.

Path parameters

id string required: The unique ID of the links library item to be created or updated

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

description string
layout enum: Whether to display the links in a horizontal or vertical layout.; Values: horizontal vertical
links union oneOf[] · max items: 100 required: The list of links to display.; One of:
tags string[] · max items: 1000 · default: []: Tag IDs associated with this library item.
title string required

Responses

updated

application/json

data object required
id string · max length: 250 required: The unique ID of the links library item, as returned by the create or search endpoints.
meta object required

created

application/json

data object required
id string · max length: 250 required: The unique ID of the links library item, as returned by the create or search endpoints.
meta object required

400

invalid request

403

forbidden

409

conflict

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/links/0ee9d0ea-06a0-4a30-bf4e-be4d3ca85bf3
{
  "title": "Important Resources",
  "description": "A collection of important links",
  "links": [
    {
      "label": "Overview",
      "type": "dashboardLink",
      "destination": "dashboard-abc-123",
      "options": {
        "open_in_new_tab": false,
        "use_time_range": true,
        "use_filters": true
      }
    },
    {
      "label": "Elastic Documentation",
      "type": "externalLink",
      "destination": "https://www.elastic.co/docs",
      "options": {
        "encode_url": true,
        "open_in_new_tab": true
      }
    }
  ],
  "layout": "vertical"
}

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/links/0ee9d0ea-06a0-4a30-bf4e-be4d3ca85bf3" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Important Resources",
  "description": "A collection of important links",
  "links": [
    {
      "label": "Overview",
      "type": "dashboardLink",
      "destination": "dashboard-abc-123",
      "options": {
        "open_in_new_tab": false,
        "use_time_range": true,
        "use_filters": true
      }
    },
    {
      "label": "Elastic Documentation",
      "type": "externalLink",
      "destination": "https://www.elastic.co/docs",
      "options": {
        "encode_url": true,
        "open_in_new_tab": true
      }
    }
  ],
  "layout": "vertical"
}'

Response

No example

Request Console 1 / 2 languages

Console Kibana Dev Tools

PUT kbn:/api/links/ID
{
  "description": "A collection of important links",
  "layout": "vertical",
  "links": [
    {
      "destination": "dashboard-abc-123",
      "label": "Overview",
      "options": {
        "open_in_new_tab": false,
        "use_filters": true,
        "use_time_range": true
      },
      "type": "dashboardLink"
    },
    {
      "destination": "https://www.elastic.co/docs",
      "label": "Elastic Documentation",
      "options": {
        "encode_url": true,
        "open_in_new_tab": true
      },
      "type": "externalLink"
    }
  ],
  "title": "Important Resources"
}

Generated from the API spec

curl Shell

curl \
  -X PUT "${KIBANA_URL}/api/links/${ID}" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A collection of important links",
    "layout": "vertical",
    "links": [
      {
        "destination": "dashboard-abc-123",
        "label": "Overview",
        "options": {
          "open_in_new_tab": false,
          "use_filters": true,
          "use_time_range": true
        },
        "type": "dashboardLink"
      },
      {
        "destination": "https://www.elastic.co/docs",
        "label": "Elastic Documentation",
        "options": {
          "encode_url": true,
          "open_in_new_tab": true
        },
        "type": "externalLink"
      }
    ],
    "title": "Important Resources"
  }'

Generated from the API spec

Response

The complete updated links library item state after a full replacement. PUT replaces the entire item, so any fields omitted from the request are reset to their defaults.

{
  "data": {
    "description": "A collection of important links",
    "layout": "vertical",
    "links": [
      {
        "destination": "dashboard-abc-123",
        "label": "Overview",
        "options": {
          "open_in_new_tab": false,
          "use_filters": true,
          "use_time_range": true
        },
        "type": "dashboardLink"
      },
      {
        "destination": "https://www.elastic.co/docs",
        "label": "Elastic Documentation",
        "options": {
          "encode_url": true,
          "open_in_new_tab": true
        },
        "type": "externalLink"
      }
    ],
    "title": "Important Resources"
  },
  "id": "0ee9d0ea-06a0-4a30-bf4e-be4d3ca85bf3",
  "meta": {
    "created_at": "2026-04-13T10:00:00.000Z",
    "managed": false,
    "updated_at": "2026-04-13T11:00:00.000Z",
    "version": "WzYwLDFd"
  }
}

{
  "data": {
    "description": "A collection of important links",
    "layout": "horizontal",
    "links": [
      {
        "destination": "dashboard-abc-123",
        "label": "Overview",
        "options": {
          "open_in_new_tab": false,
          "use_filters": true,
          "use_time_range": true
        },
        "type": "dashboardLink"
      },
      {
        "destination": "https://www.elastic.co/docs",
        "label": "Elastic Documentation",
        "options": {
          "encode_url": true,
          "open_in_new_tab": true
        },
        "type": "externalLink"
      }
    ],
    "title": "Important Resources"
  },
  "id": "0ee9d0ea-06a0-4a30-bf4e-be4d3ca85bf3",
  "meta": {
    "created_at": "2026-04-13T10:00:00.000Z",
    "managed": false,
    "updated_at": "2026-04-13T10:00:00.000Z",
    "version": "WzU5LDFd"
  }
}