--- type: api title: Upsert links library item description: **Spaces method and path for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana-serverless/operation/operation-put-links-id resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana-serverless/operation/operation-put-links-id products: - Kibana --- # Upsert links library item Availability: Experimental - Server: `https://{kibana_url}` ## Paths - `PUT` `/api/links/{id}` - `PUT` `/s/{space_id}/api/links/{id}` #### Path parameters - `id` (string) — required The unique ID of the links library item to be created or updated ## Description 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. ## Authentication - Api key: `Authorization: ` You must create an API key and use the encoded value in the request header. To learn about creating keys, go to [API keys](https://www.elastic.co/docs/current/serverless/api-keys). ## Header parameters - `kbn-xsrf` (string) — required A required header to protect against CSRF attacks ## Request body `application/json` - `description` (string) — optional - `layout` (enum) — optional 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. - **type: dashboardLink** Link type. Set to dashboardLink for a link to another dashboard. - `type` (enum) — required Values: `dashboardLink` - `destination` (string) — required Linked dashboard saved object ID. - `label` (string) — optional The label of the link displayed in the UI. - `options` (object · default: { "open_in_new_tab": false, "use_filters": true, "use_time_range": true }) — optional - `open_in_new_tab` (boolean · default: false) — optional When enabled, the dashboard opens in a new browser tab. - `use_filters` (boolean · default: true) — optional When enabled, filters are passed to the opening dashboard. - `use_time_range` (boolean · default: true) — optional When enabled, time range is passed to the opening dashboard. - **type: externalLink** Link type. Set to externalLink for a URL outside Kibana. - `type` (enum) — required Values: `externalLink` - `destination` (string) — required The external URL to link to. - `label` (string) — optional The label of the link displayed in the UI. - `options` (object · default: { "encode_url": true, "open_in_new_tab": true }) — optional - `encode_url` (boolean · default: true) — optional Whether to escape the URL with percent encoding - `open_in_new_tab` (boolean · default: true) — optional Whether to open this link in a new tab when clicked. - `tags` (string[] · max items: 1000 · default: []) — optional Tag IDs associated with this library item. - `title` (string) — required ## Responses #### `200` updated `application/json` - `data` (object) - `description` (string) - `layout` (enum) Whether to display the links in a horizontal or vertical layout. Values: `horizontal`, `vertical` - `links` (union oneOf[] · max items: 100) The list of links to display. Same options as `links` - `tags` (string[] · max items: 1000 · default: []) Tag IDs associated with this library item. - `title` (string) - `id` (string · max length: 250) The unique ID of the links library item, as returned by the create or search endpoints. - `meta` (object) - `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. #### `201` created `application/json` - `data` (object) - `description` (string) - `layout` (enum) Whether to display the links in a horizontal or vertical layout. Values: `horizontal`, `vertical` - `links` (union oneOf[] · max items: 100) The list of links to display. Same options as `links` - `tags` (string[] · max items: 1000 · default: []) Tag IDs associated with this library item. - `title` (string) - `id` (string · max length: 250) The unique ID of the links library item, as returned by the create or search endpoints. - `meta` (object) - `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. #### `400` invalid request #### `403` forbidden #### `409` conflict ## Code examples #### Console ```console 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 ```curl 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 examples #### Update links library item 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. ```json { "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" } } ``` #### Create links library item response (via upsert) Returned when the upsert created a new item because no item existed with the specified ID. ```json { "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" } } ```