Datadog Notebooks simplify the way teams across an organization find and share knowledge. By bringing together live data and rich Markdown text, Notebooks help teams create powerful, data-driven documents—from runbooks and support playbooks to incident postmortems and data reports. And with collaboration functionalities like real-time editing and commenting, team members can simultaneously make changes to a document and gather feedback along the way. Today, we’re excited to announce the launch of our new Notebooks API, which gives you the flexibility to create and update your Notebooks programmatically, as part of your existing workflows.

In this post, we’ll show how you can use the Notebooks API to automatically:

• Generate notebooks on new services and monitors

• Keep your notebooks up-to-date

• Create offline backups of your notebooks

Automatically generate notebooks on new services and monitors

We built our Notebooks API to help you seamlessly integrate data-driven documents into your existing workflows. As you create new application services, you can call the POST endpoint to automatically generate notebooks and populate them with graphs to help you better explore your data. You can make the call from the command line, as shown below, or integrate it into the setup scripts for your service. In this example, we are creating a support playbook for the web-store service, and adding a graph that shows the average system load over a minute:

curl --location --request POST 'https://app.datadoghq.com/api/v1/notebooks' \
--header 'Content-Type: application/json' \
--header 'dd-api-key: ${api_key}' \
--header 'dd-application-key: ${application_key}' \
--data-raw '{
    "data": {
        "type": "notebooks",
        "attributes": {
            "name": "Web-store playbook",
            "cells": [
                {
                    "attributes": {
                        "definition": {
                            "show_legend": true,
                            "type": "timeseries",
                            "requests": [
                                {
                                    "q": "avg:system.load.1{*}",
                                    "style": {
                                        "line_width": "normal",
                                        "palette": "dog_classic",
                                        "line_type": "solid"
                                    },
                                    "display_type": "line"
                                }
                            ],
                            "yaxis": {
                                "scale": "linear"
                            }
                        },
                        "graph_size": "m",
                        "split_by": {
                            "keys": [],
                            "tags": []
                        },
                        "time": null
                    },
                    "type": "notebook_cells"
                }
            ],
            "time": {
                "live_span": "1h"
            },
            "status": "published"
        }
    }
}'

Now, if we head over to our Datadog account, we can see that the notebook was successfully created:

To further automate your monitoring workflows, you can chain the Notebooks API to other Datadog APIs and perform multiple calls at once. For instance, when you create a monitor using the Monitors API, you can include a call to the Notebooks API to automatically add a graph of the monitor query to an incident response playbook along with a list of recommended remediation steps. You can then add the playbook link, along with other useful resources, to the description of the monitor. This way, if the monitor triggers, it is easy for your incident response team to get the context they need to resolve the issue as quickly as possible.

Keep your library of notebooks up-to-date

Modern applications are constantly in flux, which is why we’ve made the maintenance of notebooks as quick, easy, and as hands-free as possible. When a service evolves—such as when its underlying infrastructure changes or a new feature is rolled out—you can include a call to the GET endpoint to retrieve all your notebooks that contain the name of that service in their title. You can then update each notebook by adding new graphs or modifying existing Markdown cells so that they reflect the latest state of your service. You can also incorporate the DELETE endpoint into your service deprecation process to remove notebooks associated with outdated services.

Create offline backups of your notebooks

Since notebooks are updated as services evolve—and often by multiple team members—it can be valuable to create backups of these notebooks to reference in the future. You can easily retrieve your notebook’s definition with the GET endpoint and store it for your team’s records. This way, you can see what your notebook looked like at a particular point in time. Doing this periodically means that you no longer have to worry about losing past versions of notebooks as you continue to update your records.

curl --location --request GET 'https://app.datadoghq.com/api/v1/notebooks/${notebook_id} \
--header 'dd-api-key: ${api_key}' \
--header 'dd-application-key: ${application_key}'

Start using the Notebooks API today

Having rich, easily accessible documentation is crucial for giving stakeholders across an organization the context they need to make decisions. And with the Datadog Notebooks API, you can programmatically create and update your notebooks within your existing workflows. If you’re currently using Datadog, head over to our documentation to see the full list of available endpoints. Otherwise, you can get started with a 14-day free trial today.