Kibana Security Timeline API API
You can create Timelines and Timeline templates via the API, as well as import new Timelines from an ndjson file.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Security Timeline API API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: You can create Timelines and Timeline templates via the API, as well as import new Timelines from an ndjson file.
name: Security Timeline API
x-displayName: Security timeline
paths:
/api/note:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/note</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Deletes notes by saved object ID. Send either `noteId` (single ID) or `noteIds` (array of IDs) in the JSON body.
The response has HTTP 200 with an empty body on success.
Requires the **Timeline and Notes** write privilege (`notes_write`).
'
operationId: DeleteNote
requestBody:
content:
application/json:
examples:
deleteOne:
summary: Delete a single note by id
value:
noteId: 709f99c6-89b6-4953-9160-35945c8e174e
schema:
oneOf:
- nullable: true
type: object
properties:
noteId:
description: Saved object ID of the note to delete.
type: string
required:
- noteId
- nullable: true
type: object
properties:
noteIds:
description: Saved object IDs of the notes to delete.
items:
type: string
nullable: true
type: array
required:
- noteIds
description: 'Exactly one shape: `{ "noteId": "<id>" }` for a single delete, or `{ "noteIds": ["<id>", ...] }` for bulk delete.
`noteIds` may be null in some clients; prefer an empty array or omit unused fields when possible.
'
required: true
responses:
'200':
description: The notes were deleted successfully. Response body is empty.
summary: Delete one or more notes
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/note</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns Security Timeline notes as saved objects.
**Query modes (mutually exclusive branches on the server):**
1. **`documentIds` is set** — Returns notes whose `eventId` matches the given Elasticsearch document `_id` (single string or array). Pagination query parameters (`page`, `perPage`, etc.) are **not** applied; the server uses a fixed page size (up to 10000 notes).
2. **`savedObjectIds` is set** — Returns notes linked to the given Timeline saved object id(s). Same fixed cap as above; list-mode query parameters are **not** applied.
3. **Neither `documentIds` nor `savedObjectIds`** — Lists notes using saved-objects find semantics: `page` (default 1), `perPage` (default 10), optional `search`, `sortField`, `sortOrder`, `filter`, `createdByFilter`, and `associatedFilter`.
Requires the **Timeline and Notes** read privilege (`notes_read`).
'
operationId: GetNotes
parameters:
- description: 'Event document `_id` values to match against each note''s `eventId`. When this parameter is present, the response is all matching notes (up to the server''s hard limit), not a paged list using `page`/`perPage`.
'
examples:
multiple:
summary: Multiple document ids (array)
value:
- id-one
- id-two
single:
summary: Single document id
value: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b
in: query
name: documentIds
schema:
$ref: '#/components/schemas/Security_Timeline_API_DocumentIds'
- description: 'Timeline `savedObjectId` value(s). Returns notes that reference those timelines. When present, list-mode pagination parameters are not used; up to the server''s hard limit of notes may be returned.
'
examples:
singleTimeline:
summary: Single timeline id
value: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
in: query
name: savedObjectIds
schema:
$ref: '#/components/schemas/Security_Timeline_API_SavedObjectIds'
- description: 'Page number for list mode (when `documentIds` and `savedObjectIds` are omitted). Passed as a string; default 1.
'
example: '1'
in: query
name: page
schema:
nullable: true
type: string
- description: 'Page size for list mode (when `documentIds` and `savedObjectIds` are omitted). Passed as a string; default 10.
'
example: '20'
in: query
name: perPage
schema:
nullable: true
type: string
- description: Search string for saved-objects find (list mode only).
in: query
name: search
schema:
nullable: true
type: string
- description: Field to sort by for saved-objects find (list mode only).
in: query
name: sortField
schema:
nullable: true
type: string
- description: Sort order (`asc` or `desc`) for saved-objects find (list mode only).
example: desc
in: query
name: sortOrder
schema:
nullable: true
type: string
- description: 'Kuery filter string combined with other list-mode filters (for example `createdByFilter` or `associatedFilter`). Typed as a string for API compatibility; interpreted by the saved-objects layer (list mode only).
'
in: query
name: filter
schema:
nullable: true
type: string
- description: 'Kibana user profile **UID** (UUID). The server resolves the user''s display identifiers and returns notes whose `createdBy` matches any of them (list mode only).
'
example: f1c2d3e4-5b6a-7890-abcd-ef1234567890
in: query
name: createdByFilter
schema:
nullable: true
type: string
- description: 'Restricts notes by how they relate to a Timeline and/or an event document (list mode only). Some values apply extra filtering after the query. Ignored when `documentIds` or `savedObjectIds` is used.
'
in: query
name: associatedFilter
schema:
$ref: '#/components/schemas/Security_Timeline_API_AssociatedFilterType'
responses:
'200':
content:
application/json:
examples:
notesPage:
summary: Paged notes for a timeline
value:
notes:
- eventId: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
note: Escalated to tier-2 analyst
noteId: 709f99c6-89b6-4953-9160-35945c8e174e
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
version: WzQ2LDFd
totalCount: 1
schema:
$ref: '#/components/schemas/Security_Timeline_API_GetNotesResult'
description: Notes and total count for the requested mode.
summary: Get notes
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
patch:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb patch">patch</span> <span class="operation-path">/s/{space_id}/api/note</span></div>
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`).
'
externalDocs:
description: Add or update a note on a Timeline
url: https://www.elastic.co/guide/en/security/current/timeline-api-update.html
operationId: PersistNoteRoute
requestBody:
content:
application/json:
examples:
addNote:
summary: Add a note on an event
value:
note:
eventId: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
note: Escalated to tier-2 analyst
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
schema:
type: object
properties:
note:
$ref: '#/components/schemas/Security_Timeline_API_BareNote'
description: Note payload (timeline, text, optional event linkage, metadata).
noteId:
description: The `savedObjectId` of the note to update. Omit when creating a new note.
example: 709f99c6-89b6-4953-9160-35945c8e174e
nullable: true
type: string
version:
description: Saved object version string from a previous read; optional on update.
example: WzQ2LDFd
nullable: true
type: string
required:
- note
description: '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.
'
required: true
responses:
'200':
content:
application/json:
examples:
persisted:
summary: Persisted note wrapper
value:
note:
eventId: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
note: Escalated to tier-2 analyst
noteId: 709f99c6-89b6-4953-9160-35945c8e174e
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
version: WzQ2LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_ResponseNote'
description: The persisted note, including `noteId` and `version`.
summary: Add or update a note
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
/api/pinned_event:
patch:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb patch">patch</span> <span class="operation-path">/s/{space_id}/api/pinned_event</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Pin/unpin an event to/from an existing Timeline.'
operationId: PersistPinnedEventRoute
requestBody:
content:
application/json:
examples:
pinEvent:
summary: Pin an event
value:
eventId: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
schema:
type: object
properties:
eventId:
description: The `_id` of the associated event for this pinned event.
example: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
type: string
pinnedEventId:
description: The `savedObjectId` of the pinned event you want to unpin.
example: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
nullable: true
type: string
timelineId:
description: The `savedObjectId` of the timeline that you want this pinned event unpinned from.
example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
type: string
required:
- eventId
- timelineId
description: The pinned event to add or unpin, along with additional metadata.
required: true
responses:
'200':
content:
application/json:
examples:
pinnedSaved:
summary: Pinned event saved object
value:
eventId: d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc
pinnedEventId: 10r1929b-0af7-42bd-85a8-56e234f98h2f3
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
version: WzQ2LDFe
unpinned:
summary: Unpin response
value:
unpinned: true
schema:
$ref: '#/components/schemas/Security_Timeline_API_PersistPinnedEventResponse'
description: Indicates a successful call.
summary: Pin/unpin an event
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
/api/timeline:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/timeline</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Delete one or more Timelines or Timeline templates.'
operationId: DeleteTimelines
requestBody:
content:
application/json:
examples:
deleteByIds:
summary: Delete timelines by saved object id
value:
savedObjectIds:
- 15c1929b-0af7-42bd-85a8-56e234cc7c4e
deleteWithSearches:
summary: Delete Timelines and their linked saved searches
value:
savedObjectIds:
- 15c1929b-0af7-42bd-85a8-56e234cc7c4e
- 6ce1b592-84e3-4b4a-9552-f189d4b82075
searchIds:
- 2c1b8f02-9ad6-4e33-8f6a-2c6b7d0a1f11
schema:
type: object
properties:
savedObjectIds:
description: The list of IDs of the Timelines or Timeline templates to delete
items:
type: string
maxItems: 100
type: array
searchIds:
description: Saved search IDs that should be deleted alongside the timelines
items:
type: string
maxItems: 100
type: array
required:
- savedObjectIds
description: The IDs of the Timelines or Timeline templates to delete.
required: true
responses:
'200':
content:
application/json:
examples:
success:
summary: Success
value: {}
schema:
additionalProperties: true
type: object
description: Indicates a successful call.
summary: Delete Timelines or Timeline templates
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/timeline</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the details of an existing saved Timeline or Timeline template.'
operationId: GetTimeline
parameters:
- description: The `savedObjectId` of the Timeline template to retrieve.
in: query
name: template_timeline_id
schema:
type: string
- description: The `savedObjectId` of the Timeline to retrieve.
in: query
name: id
schema:
type: string
responses:
'200':
content:
application/json:
examples:
timelineDetail:
summary: Timeline detail
value:
description: User-reported suspicious email
noteIds: []
pinnedEventIds: []
savedObjectId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
status: active
timelineType: default
title: Phishing investigation
version: WzE0LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
description: Indicates a successful call.
summary: Get Timeline or Timeline template details
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
patch:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb patch">patch</span> <span class="operation-path">/s/{space_id}/api/timeline</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update an existing Timeline. You can update the title, description, date range, pinned events, pinned queries, and/or pinned saved queries of an existing Timeline.'
operationId: PatchTimeline
requestBody:
content:
application/json:
examples:
patchTitle:
summary: Update title
value:
timeline:
title: Escalated case review
timelineId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
version: WzE0LDFd
schema:
type: object
properties:
timeline:
$ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
description: The timeline object of the Timeline or Timeline template that you’re updating.
timelineId:
description: The `savedObjectId` of the Timeline or Timeline template that you’re updating.
example: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
nullable: true
type: string
version:
description: The version of the Timeline or Timeline template that you’re updating.
example: WzE0LDFd
nullable: true
type: string
required:
- timelineId
- version
- timeline
description: The Timeline updates, along with the Timeline ID and version.
required: true
responses:
'200':
content:
application/json:
examples:
patched:
summary: Updated timeline
value:
savedObjectId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
status: active
timelineType: default
title: Escalated case review
version: WzE1LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
description: Indicates a successful call.
'405':
content:
application/json:
examples:
error:
summary: Error body
value:
body: update timeline error
statusCode: 405
schema:
type: object
properties:
body:
description: The error message.
example: update timeline error
type: string
statusCode:
example: 405
type: number
description: Indicates that the user does not have the required access to create a Timeline.
summary: Update a Timeline
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/timeline</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create a new Timeline or Timeline template.'
operationId: CreateTimelines
requestBody:
content:
application/json:
examples:
createDefault:
summary: Create a default timeline
value:
timeline:
status: active
timelineType: default
title: Malware containment
schema:
type: object
properties:
status:
$ref: '#/components/schemas/Security_Timeline_API_TimelineStatus'
nullable: true
templateTimelineId:
description: A unique identifier for the Timeline template.
example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
nullable: true
type: string
templateTimelineVersion:
description: Timeline template version number.
example: 12
nullable: true
type: number
timeline:
$ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
timelineId:
description: A unique identifier for the Timeline.
example: 6ce1b592-84e3-4b4a-9552-f189d4b82075
nullable: true
type: string
timelineType:
$ref: '#/components/schemas/Security_Timeline_API_TimelineType'
nullable: true
version:
nullable: true
type: string
required:
- timeline
description: The required Timeline fields used to create a new Timeline, along with optional fields that will be created if not provided.
required: true
responses:
'200':
content:
application/json:
examples:
created:
summary: Created timeline
value:
savedObjectId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
status: active
timelineType: default
title: Malware containment
version: WzE0LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
description: Indicates a successful call.
'405':
content:
application/json:
examples:
error:
summary: Error body
value:
body: update timeline error
statusCode: 405
schema:
type: object
properties:
body:
description: The error message
example: update timeline error
type: string
statusCode:
example: 405
type: number
description: Indicates that there was an error in the Timeline creation.
summary: Create a Timeline or Timeline template
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
/api/timeline/_copy:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/timeline/_copy</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Copies and returns a timeline or timeline template.
'
operationId: CopyTimeline
requestBody:
content:
application/json:
examples:
copyWithTitle:
summary: Copy with a new title
value:
timeline:
timelineType: default
title: Copy of investigation
timelineIdToCopy: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
schema:
type: object
properties:
timeline:
$ref: '#/components/schemas/Security_Timeline_API_SavedTimeline'
timelineIdToCopy:
description: The `savedObjectId` of the timeline or template to duplicate.
type: string
required:
- timeline
- timelineIdToCopy
description: Source timeline id to copy plus timeline fields for the new saved object.
required: true
responses:
'200':
content:
application/json:
examples:
copied:
summary: Newly saved timeline
value:
savedObjectId: 6ce1b592-84e3-4b4a-9552-f189d4b82075
status: active
timelineType: default
title: Copy of investigation
version: WzE1LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
description: Indicates a successful call.
summary: Copies timeline or timeline template
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
/api/timeline/_draft:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/timeline/_draft</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the details of the draft Timeline or Timeline template for the current user. If the user doesn''t have a draft Timeline, an empty Timeline is returned.'
operationId: GetDraftTimelines
parameters:
- description: Which draft to load (`default` investigation timeline or `template` timeline template).
in: query
name: timelineType
required: true
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineType'
responses:
'200':
content:
application/json:
examples:
draftPayload:
summary: Draft timeline payload
value:
savedObjectId: 15c1929b-0af7-42bd-85a8-56e234cc7c4e
status: draft
timelineType: default
title: ''
version: WzE0LDFd
schema:
$ref: '#/components/schemas/Security_Timeline_API_TimelineResponse'
description: Indicates a successful call.
'403':
content:
application/json:
examples:
forbidden:
summary: Permission denied
value:
message: Forbidden
status_code: 403
schema:
type: object
properties:
message:
type: string
status_code:
type: number
description: If a draft Timeline was not found and we attempted to create one, it indicates that the user does not have the required permissions to create a draft Timeline.
'409':
content:
application/json:
examples:
conflict:
summary: Draft conflict
value:
message: Conflict
status_code: 409
schema:
type: object
properties:
message:
type: string
status_code:
type: number
description: This should never happen, but if a draft Timeline was not found and we attempted to create one, it indicates that there is already a draft Timeline with the given `timelineId`.
summary: Get draft Timeline or Timeline template details
tags:
- Security Timeline API
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/timeline/_draft</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create a clean draft Timeline or Timeline template for the current user.
> info
> If the user already has a draft Timeline, the existing draft Timeline is cleared and returned.
'
operationId: CleanDraftTimelines
requestBody:
content:
application/json:
examples:
defaultDraft:
summary: Create a default draft tim
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-security-timeline-api-api-openapi.yml