Upsert links library item Experimental; added in 9.6.0

PUT /api/links/{id}
Api key auth Basic auth

Spaces method and path for this operation:

put /s/{space_id}/api/links/{id}

Refer to Spaces for more information.

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.

application/json

Body

  • description string
  • layout string

    Whether to display the links in a horizontal or vertical layout.

    Values are horizontal or vertical.

  • links array[object] Required

    The list of links to display.

    Not more than 100 elements.

    One of:
    dashboardLink object externalLink object
  • tags array[string]

    Tag IDs associated with this library item.

    Not more than 1000 elements. Maximum length of each is 250. Default value is [] (empty).

  • title string Required
PUT /api/links/{id} 
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"
}'
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"
}
Request example 
{
  "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"
}
Response examples (200)
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"
  }
}
Response examples (201)
Returned when the upsert created a new item because no item existed with the specified ID. 
{
  "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"
  }
}