---
title: "Upsert links library item"
method: PUT
path: "/api/links/{id}"
tags: ["Links"]
---

# Upsert links library item

`PUT /api/links/{id}`

**Spaces method and path for this operation:**

<div><span class="operation-verb put">put</span>&nbsp;<span class="operation-path">/s/{space_id}/api/links/{id}</span></div>

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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.

## Path parameters

- `id` string, required

## Headers

- `kbn-xsrf` string, required

## Request body

- object
  - `description` string
  - `layout` 'horizontal' | 'vertical' — Whether to display the links in a horizontal or vertical layout.
  - `links` union[], required — The list of links to display.
    - union
      - KibanaHTTPAPIsKbnLinkPanelTypeDashboardLink — Link type. Set to dashboardLink for a link to another dashboard.
        - `destination` string, required — Linked dashboard saved object ID.
        - `label` string — The label of the link displayed in the UI.
        - `options` object
          - `open_in_new_tab` boolean — When enabled, the dashboard opens in a new browser tab.
          - `use_filters` boolean — When enabled, filters are passed to the opening dashboard.
          - `use_time_range` boolean — When enabled, time range is passed to the opening dashboard.
        - `type` 'dashboardLink', required
      - KibanaHTTPAPIsKbnLinkTypeExternalLink — Link type. Set to externalLink for a URL outside Kibana.
        - `destination` string, required — The external URL to link to.
        - `label` string — The label of the link displayed in the UI.
        - `options` object
          - `encode_url` boolean — Whether to escape the URL with percent encoding
          - `open_in_new_tab` boolean — Whether to open this link in a new tab when clicked.
        - `type` 'externalLink', required
  - `tags` string[] — Tag IDs associated with this library item.
  - `title` string, required

## Response `200`

updated

- KibanaHTTPAPIsLinksItemResponse — Response containing a links library item with metadata.
  - `data` object, required
    - `description` string
    - `layout` 'horizontal' | 'vertical' — Whether to display the links in a horizontal or vertical layout.
    - `links` union[], required — The list of links to display.
      - union
        - KibanaHTTPAPIsKbnLinkPanelTypeDashboardLink — Link type. Set to dashboardLink for a link to another dashboard.
          - `destination` string, required — Linked dashboard saved object ID.
          - `label` string — The label of the link displayed in the UI.
          - `options` object
            - `open_in_new_tab` boolean — When enabled, the dashboard opens in a new browser tab.
            - `use_filters` boolean — When enabled, filters are passed to the opening dashboard.
            - `use_time_range` boolean — When enabled, time range is passed to the opening dashboard.
          - `type` 'dashboardLink', required
        - KibanaHTTPAPIsKbnLinkTypeExternalLink — Link type. Set to externalLink for a URL outside Kibana.
          - `destination` string, required — The external URL to link to.
          - `label` string — The label of the link displayed in the UI.
          - `options` object
            - `encode_url` boolean — Whether to escape the URL with percent encoding
            - `open_in_new_tab` boolean — Whether to open this link in a new tab when clicked.
          - `type` 'externalLink', required
    - `tags` string[] — Tag IDs associated with this library item.
    - `title` string, required
  - `id` string, required — The unique ID of the links library item, as returned by the create or search endpoints.
  - `meta` KibanaHTTPAPIsKbnAsCodeMeta, required
    - `created_at` string — Timestamp when the object was created (ISO 8601).
    - `created_by` string — User profile ID of the user who created the object.
    - `managed` boolean — When `true`, the object is managed by Kibana and cannot be edited by users.
    - `owner` string — Identifier of the plugin or team that owns this object.
    - `updated_at` string — Timestamp when the object was last updated (ISO 8601).
    - `updated_by` string — User profile ID of the user who last updated the object.
    - `version` string — Internal version identifier for optimistic concurrency control.

## Other responses

- `201` — created
- `400` — invalid request
- `403` — forbidden
- `409` — conflict

---

[API](https://skmtc.net/elastic/apis/kibana-apis.md) · [All operations](https://skmtc.net/elastic/apis/kibana-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elastic/kibana-apis/versions/531c9e2a7d23/schema)