---
type: api
title: Add or update a note
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-persistnoteroute
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-persistnoteroute
products:
  - Kibana
---

# Add or update a note

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

## Paths

- `PATCH` `/api/note`
- `PATCH` `/s/{space_id}/api/note`

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

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Creates a new note or updates an existing one.

**Create:** Send `note` and omit `noteId` to create a new saved object.

**Update:** Send `note` with the changed fields and set `noteId` to the note's saved object ID. Optionally include `version` for optimistic concurrency when the client has it from a prior read.

Requires the **Timeline and Notes** write privilege (`notes_write`).

[Add or update a note on a Timeline](https://www.elastic.co/guide/en/security/current/timeline-api-update.html)

## Request Body

`application/json`

Body must include the `note` object. For updates, include `noteId` (and optionally `version`).
To attach a note to a specific event, set `note.eventId` to that event's document `_id`; for a timeline-wide note, omit or clear `eventId` per product rules.

- `note` ({}) — required
  - `created` (number) — optional — nullable
    The time the note was created, using a 13-digit Epoch timestamp.
  - `createdBy` (string) — optional — nullable
    The user who created the note.
  - `updated` (number) — optional — nullable
    The last time the note was updated, using a 13-digit Epoch timestamp
  - `updatedBy` (string) — optional — nullable
    The user who last updated the note
  - `eventId` (string) — optional — nullable
    Elasticsearch document `_id` for the event or alert this note refers to. Same value as the `documentIds` query parameter when fetching notes via GET /api/note.
  - `note` (string) — optional — nullable
    The text of the note
  - `timelineId` (string) — required
    The `savedObjectId` of the Timeline this note belongs to (not the note's own ID).
- `noteId` (string) — optional — nullable
  The `savedObjectId` of the note to update. Omit when creating a new note.
- `version` (string) — optional — nullable
  Saved object version string from a previous read; optional on update.

## Response

The persisted note, including `noteId` and `version`.

`application/json`

- `note` ({})
  - `created` (number) — nullable
    The time the note was created, using a 13-digit Epoch timestamp.
  - `createdBy` (string) — nullable
    The user who created the note.
  - `updated` (number) — nullable
    The last time the note was updated, using a 13-digit Epoch timestamp
  - `updatedBy` (string) — nullable
    The user who last updated the note
  - `eventId` (string) — nullable
    Elasticsearch document `_id` for the event or alert this note refers to. Same value as the `documentIds` query parameter when fetching notes via GET /api/note.
  - `note` (string) — nullable
    The text of the note
  - `timelineId` (string)
    The `savedObjectId` of the Timeline this note belongs to (not the note's own ID).
  - `noteId` (string)
    The `savedObjectId` of the note
  - `version` (string)
    The version of the note
## Code Examples

#### Console

```console
PATCH /api/note
{
  "note": {
    "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
    "note": "Escalated to tier-2 analyst",
    "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e"
  }
}
```

#### curl

```curl
curl -X PATCH "https://{kibana_url}/api/note" \
  -H "Content-Type: application/json" \
  -d '{
  "note": {
    "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
    "note": "Escalated to tier-2 analyst",
    "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e"
  }
}'
```

## Response Examples

#### Persisted note wrapper

```json
{
  "note": {
    "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
    "note": "Escalated to tier-2 analyst",
    "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
    "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
    "version": "WzQ2LDFd"
  }
}
```