---
type: api
title: Upsert a markdown library item
description: Replaces the full state of a markdown library item. Partial updates are not supported.
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-put-markdowns-id
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/v0/operation/operation-put-markdowns-id
products:
  - Kibana
---

# Upsert a markdown library item

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/markdowns/{id}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/v0/authentication#basicauth)

#### Path Parameters

- `id` (string)
  The unique ID of the markdown library item to be created or updated.

## Description

Replaces the full state of a markdown 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.

## Request Body

`application/json`

- `content` (string) — required
  The Markdown text rendered by the panel. Supports GitHub-flavored Markdown, including headings, paragraphs, lists, links, images, tables, blockquotes, and code blocks. Use `\n` for line breaks within JSON strings.
- `description` (string) — optional
  A short description of the markdown library item.
- `settings` (object · default: {
  "open_links_in_new_tab": true
}) — optional
  Display settings for the markdown panel.
  - `open_links_in_new_tab` (boolean · default: true) — optional
    Open links in a new browser tab.
- `title` (string · min: 1) — required
  The markdown library item title.

## Responses

#### `200`

updated

`application/json`

- `data` (object)
  - `content` (string)
    The Markdown text rendered by the panel. Supports GitHub-flavored Markdown, including headings, paragraphs, lists, links, images, tables, blockquotes, and code blocks. Use `\n` for line breaks within JSON strings.
  - `description` (string)
    A short description of the markdown library item.
  - `settings` (object · default: {
  "open_links_in_new_tab": true
})
    Display settings for the markdown panel.
    - `open_links_in_new_tab` (boolean · default: true)
      Open links in a new browser tab.
  - `title` (string · min: 1)
    The markdown library item title.
- `id` (string)
  The unique ID of the markdown library item, as returned by the create or search endpoints.
- `meta` ({})
  - `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)
  - `content` (string)
    The Markdown text rendered by the panel. Supports GitHub-flavored Markdown, including headings, paragraphs, lists, links, images, tables, blockquotes, and code blocks. Use `\n` for line breaks within JSON strings.
  - `description` (string)
    A short description of the markdown library item.
  - `settings` (object · default: {
  "open_links_in_new_tab": true
})
    Display settings for the markdown panel.
    - `open_links_in_new_tab` (boolean · default: true)
      Open links in a new browser tab.
  - `title` (string · min: 1)
    The markdown library item title.
- `id` (string)
  The unique ID of the markdown library item, as returned by the create or search endpoints.
- `meta` ({})
  - `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

## Code Examples

#### Console

```console
PUT kbn:/api/markdowns/5e1f3a20-c4d6-11ef-be8b-3c7c2b9d1f4e
{
  "title": "Web logs overview",
  "description": "Intro and context for the web logs dashboard.",
  "content": "## Web logs overview\n\nA quick reference for the **Kibana sample web logs** dataset (`kibana_sample_data_logs`).\n\n**Key metrics in this dashboard:**\n\n- Total request count by HTTP method\n- Average response size over time\n- Geographic distribution of client IPs\n- _New:_ error rate broken down by status code\n\n> Use the time picker above to narrow the dashboard to an incident window.\n\nFor field reference, see the [sample data documentation](https://www.elastic.co/docs/manage-data/ingest/sample-data).\n",
  "settings": {
    "open_links_in_new_tab": true
  }
}
```

#### curl

```curl
curl -X PUT "${KIBANA_URL}/api/markdowns/5e1f3a20-c4d6-11ef-be8b-3c7c2b9d1f4e" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Web logs overview",
  "description": "Intro and context for the web logs dashboard.",
  "content": "## Web logs overview\n\nA quick reference for the **Kibana sample web logs** dataset (`kibana_sample_data_logs`).\n\n**Key metrics in this dashboard:**\n\n- Total request count by HTTP method\n- Average response size over time\n- Geographic distribution of client IPs\n- _New:_ error rate broken down by status code\n\n> Use the time picker above to narrow the dashboard to an incident window.\n\nFor field reference, see the [sample data documentation](https://www.elastic.co/docs/manage-data/ingest/sample-data).\n",
  "settings": {
    "open_links_in_new_tab": true
  }
}'
```

## Response Examples

#### Update markdown library item response

The complete updated markdown 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": {
    "content": "## Web logs overview\n\nA quick reference for the **Kibana sample web logs** dataset (\u0060kibana_sample_data_logs\u0060).\n\n**Key metrics in this dashboard:**\n\n- Total request count by HTTP method\n- Average response size over time\n- Geographic distribution of client IPs\n- _New:_ error rate broken down by status code\n\n\u003E Use the time picker above to narrow the dashboard to an incident window.\n\nFor field reference, see the [sample data documentation](https://www.elastic.co/docs/manage-data/ingest/sample-data).\n",
    "description": "Intro and context for the web logs dashboard.",
    "settings": {
      "open_links_in_new_tab": true
    },
    "title": "Web logs overview"
  },
  "id": "5e1f3a20-c4d6-11ef-be8b-3c7c2b9d1f4e",
  "meta": {
    "created_at": "2026-04-13T10:00:00.000Z",
    "managed": false,
    "updated_at": "2026-04-13T11:00:00.000Z",
    "version": "WzYwLDFd"
  }
}
```

#### Create markdown library item response (via upsert)

Returned when the upsert created a new item because no item existed with the specified ID.

```json
{
  "data": {
    "content": "## Web logs overview\n\nA quick reference for the **Kibana sample web logs** dataset (\u0060kibana_sample_data_logs\u0060).\n\n**Key metrics in this dashboard:**\n\n- Total request count by HTTP method\n- Average response size over time\n- Geographic distribution of client IPs\n\n\u003E Use the time picker above to narrow the dashboard to an incident window.\n\nFor field reference, see the [sample data documentation](https://www.elastic.co/docs/manage-data/ingest/sample-data).\n",
    "description": "Intro and context for the web logs dashboard.",
    "settings": {
      "open_links_in_new_tab": true
    },
    "title": "Web logs overview"
  },
  "id": "web-logs-overview",
  "meta": {
    "created_at": "2026-04-13T10:00:00.000Z",
    "managed": false,
    "updated_at": "2026-04-13T10:00:00.000Z",
    "version": "WzU5LDFd"
  }
}
```