[role="xpack"]
[testenv="platinum"]
[[ml-post-calendar-event]]
=== Add events to calendar API
++++
<titleabbrev>Add events to calendar</titleabbrev>
++++

Posts scheduled events in a calendar.

==== Request

`POST _ml/calendars/<calendar_id>/events`


==== Description

This API accepts a list of {xpack-ref}/ml-calendars.html[scheduled events], each
of which must have a start time, end time, and description.

==== Path Parameters

`calendar_id` (required)::
		(string) Identifier for the calendar.


==== Request Body

`events`::
  (array) A list of one of more scheduled events. The event's start and end times
  may be specified as integer milliseconds since the epoch or as a string in ISO 8601
  format. See <<ml-event-resource>>.


==== Authorization

You must have `manage_ml`, or `manage` cluster privileges to use this API.
For more information, see
{xpack-ref}/security-privileges.html[Security Privileges].


==== Examples

You can add scheduled events to the `planned-outages` calendar as follows:

[source,js]
--------------------------------------------------
POST _ml/calendars/planned-outages/events
{
  "events" : [
    {"description": "event 1", "start_time": 1513641600000, "end_time": 1513728000000},
    {"description": "event 2", "start_time": 1513814400000, "end_time": 1513900800000},
    {"description": "event 3", "start_time": 1514160000000, "end_time": 1514246400000}
  ]
}
--------------------------------------------------
// CONSOLE
// TEST[skip:setup:calendar_outages_addjob]

The API returns the following results:

[source,js]
----
{
  "events": [
    {
      "description": "event 1",
      "start_time": 1513641600000,
      "end_time": 1513728000000,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 2",
      "start_time": 1513814400000,
      "end_time": 1513900800000,
      "calendar_id": "planned-outages"
    },
    {
      "description": "event 3",
      "start_time": 1514160000000,
      "end_time": 1514246400000,
      "calendar_id": "planned-outages"
    }
  ]
}
----
// TESTRESPONSE

For more information about these properties, see
<<ml-event-resource,Scheduled Event Resources>>.