Midnight API Documentation

Overview

With Midnight's REST API you can interact with your Midnight data programatically. It is included with both Basic and Pro memberships. Before using the API, you'll need to generate a secret API Key on the Account Page. All Midnight API requests are made to the https://api.midnight.app/v1/events endpoint.

Creating Events

Reading The Current Event

Reading One Event

Reading Multiple Events

Updating Events

Updating Start & End Time

Deleting Events

Creating Events POST /api/v1/events

title: The title of the event. Required.
start (optional): The start time of the event. Can be an ISO 8601 or JavaScript timestamp.

To add a new event, send a POST request to `/api/v1/events`. A successful request will return a 201 Created status with a JSON object of the new event.

createEvents.sh


curl -X POST https://api.midnight.app/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"title": "reading API documentation #work"}'
            
curl -X POST https://api.midnight.app/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"title": "reading API documentation #work", "start": "2024-01-01T00:00:00Z"}'
            
curl -X POST https://api.midnight.app/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"title": "reading API documentation #work", "start": "1888492245000"}'

{
  "data": {
    "id": "5jn4k90OpmZk5p9d2EA", 
    "title": "reading API documentation #work",
    "start": "2024-03-02T10:00:00Z"
    "end": "2024-03-02T11:00:00Z",
    "duration": "3600000",
    "previousEventId": null,
    "nextEventId": "T63uk90Op5ZkKo9plKad",
    "tags": ["tag"]
  }
}

Reading The Current Event GET /api/v1/events/now

To get the current event, send a GET request to `/api/v1/events/now`. A successful request returns a 200 OK status and a JSON object of the current event.

currentEvent.sh

curl -X GET https://api.midnight.app/v1/events/now \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
      "id": "5jn4k90OpmZk5p9d2EA", 
      "title": "Current Event Title #tag",
      "start": "2024-03-02T10:00:00Z"
      "end": "2024-03-02T11:00:00Z",
      "duration": "3600000",
      "previousEventId": null,
      "nextEventId": "T63uk90Op5ZkKo9plKad",
      "tags": ["tag"]
  }
}

Reading A Specific Event by ID GET /api/v1/events/:id

To get a specific event, send a GET request to `/api/v1/events/:id`. A successful request returns a 200 OK status and a JSON object of the event.

eventById.sh

curl -X GET https://api.midnight.app/v1/events/YOUR_EVENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "5jn4k90OpmZk5p9d2EA", 
    "title": "Specific Event Title #tag",
    "start": "2024-03-02T10:00:00Z"
    "end": "2024-03-02T11:00:00Z",
    "duration": "3600000",
    "previousEventId": null,
    "nextEventId": "T63uk90Op5ZkKo9plKad",
    "tags": ["tag"]
  }
}

Reading Multiple Events GET /api/v1/events

start (optional): Date from when to start listing events. Defaults to 24 hours ago.
end (optional): Date until when to list events. Defaults to either now or 24 hours after a specified start.
limit (optional): Number of events to return. Defaults to 100, with a maximum of 1000.

To get a list of events, send a GET request to `/api/v1/events`. A successful request returns a 200 OK status and an array of JSON event objects.

listAllEvents.sh

curl -X GET "https://api.midnight.app/v1/events?start=2024-02-28T11:30:00Z&end=2024-02-28T15:30:00Z" -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "5jn4k90OpmZk5p9d2EA", 
      "title": "First Event",
      "start": "2024-03-02T10:00:00Z"
      "end": "2024-03-02T11:00:00Z",
      "duration": "3600000",
      "previousEventId": null,
      "nextEventId": "T63uk90Op5ZkKo9plKad",
      "tags": []
    },
    {
      "id": "T63uk90Op5ZkKo9plKad", 
      "title": "Second Event #tag",
      "start": "2024-03-02T11:00:00Z"
      "end": "2024-03-02T12:00:00Z",
      "duration": "3600000",
      "previousEventId": "5jn4k90OpmZk5p9d2EA",
      "nextEventId": "p0injL390d4mIkd8S2l",
      "tags": ["tag"]
    }
  ]
}

Updating Events PATCH /api/v1/events/:id

title (optional): A new title for the event.
start (optional): A new start time for the event. Can be an ISO 8601 or JavaScript timestamp.

To update an event, send a PATCH request to `/api/v1/events/:id`. A successful request returns a 200 OK status and the updated event as a JSON object.

Edit Events.sh

curl -X PATCH https://api.midnight.app/v1/events/YOUR_EVENT_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"title": "Updated Event Title #tag", "start": "2024-03-02T10:00:00Z}'

{
  "data": {
    "id": "5jn4k90OpmZk5p9d2EA", 
    "title": "Updated Event Title #tag",
    "start": "2024-03-02T10:00:00Z"
    "end": "2024-03-02T11:00:00Z",
    "duration": "3600000",
    "previousEventId": null,
    "nextEventId": "T63uk90Op5ZkKo9plKad",
    "tags": ["tag"]
  }
}

Updating Events | Updating Duration & End Time

You cannot directly update an event's end time or duration in Midnight because these values are determined by the next event's start time. This means you need to modify or create another event in order to change an event's end time. If you're just trying to shorten an event, add a new #untracked event at the time you'd like the event to end. If you'd like to lengthen an event, look for the event's nextEventId and either delete it or update it's start time. You may need to do this multiple times.

Update Event Times Sequence With Next ID.sh


#Fetch the first event ID and update it
echo "Fetching the first event details to get the nextId..."
response=$(curl -s -X GET https://api.midnight.app/v1/events/YOUR_FIRST_EVENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY")
        
nextEventId=$(echo $response | jq -r '.data.nextId')
        
# Assuming you've extracted the nextId correctly
echo "Updating the first event's start time..."
curl -s -X PATCH https://api.midnight.app/v1/events/YOUR_FIRST_EVENT_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"start": "2024-03-02T10:00:00Z"}'
        
echo "Updating the next event's (ID: $nextEventId) start time..."
curl -s -X PATCH https://api.midnight.app/v1/events/$nextEventId \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"start": "2024-03-02T12:00:00Z"}'

Deleting Events DELETE /api/v1/events/:id

To delete an event, send a DELETE request to `/api/v1/events/:id`. A successful request will return 204 No Content.

removeEvents.sh

curl -X DELETE https://api.midnight.app/v1/events/YOUR_EVENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

{}