Using the Blob Storage API for notebooks

Public preview

The Blob Storage API for notebooks is currently in public preview. This feature is provided pursuant to our pre-release policies.

The New Relic Notebooks API lets you create, read, update, and delete notebooks programmatically, including their full block content (NRQL queries, text). Notebooks are stored as versioned blobs, which means every save produces a new immutable revision you can retrieve later.

Use this API to:

Automate notebook creation from incident templates, runbooks, or CI/CD pipelines
Sync notebook content from version control or external authoring tools
Build integrations that programmatically populate notebooks during investigations

Importante

Notebooks use multiple APIs

The Notebooks API surface is split between two systems:

Blob Storage API handles notebook content (blocks, version history)
NerdGraph handles entity-level operations (list, rename, tags, organization metadata)
This separation is by design. The Blob Storage API is optimized for file content transfer and versioning; NerdGraph is optimized for structured entity queries and mutations.

Prerequisites

A New Relic account with a User API key
Your New Relic Organization ID
Appropriate permissions to manage notebooks

Authentication

All Notebooks API requests require authentication using a New Relic User API key.

Generate an API key:

Navigate to one.newrelic.com
Click on your name in the top-right corner
Select API Keys
Create a User key (not Browser or License key)

Include in request headers:

bash

$Api-Key: NRAK-YOUR-USER-API-KEY

Dica

The Blob Storage API also supports login context, so when calling the API from a UI authenticated as a New Relic user, the Api-Key header is not required.

Base endpoint

https://blob-api.service.newrelic.com/v1/e

For EU region accounts, use:

https://blob-api.service.eu.newrelic.com/v1/e

Notebook content operations

Creates a new notebook entity with initial blob content.

Endpoint

POST /v1/e/organizations/{orgId}/Notebooks

Request parameters

Parameter	Location	Data type	Description
`orgId`	Path	String	Required. Your New Relic organization ID.
`Api-Key`	Header	String	Required. Your User API key.
`Content-Type`	Header	String	Required. Must be `application/json`.
`NewRelic-Entity`	Header	JSON string	Required. JSON object with notebook entity metadata (see below).
Request body	Body	JSON	Required. Notebook content in JSON format (version + blocks).

`NewRelic-Entity` header format

Field	Data type	Description
`name`	String	Required. The notebook name. Must be unique within the organization scope.

Notebook body format

Field	Data type	Description
`version`	String	Schema version of the notebook payload. Use `"1"`.
`blocks`	Array	Ordered list of notebook blocks (NRQL, text, etc.). Empty array creates a blank notebook.

Declarative UI content examples

The following examples show how to structure notebook widget content using the declarative UI format.

Markdown widget

Use viz.markdown to render static text, labels, or threshold legends alongside your charts:

{
  "type": "widget",
  "content": {
    "type": "visualization",
    "id": "viz.markdown",
    "props": {
      "text": "# My dashboard\n\n### Cost thresholds (monthly)\n- $0 – $200 → Good\n- $200 – $500 → Warning\n- $500+ → Critical"
    }
  }
}

Billboard widget with NRQL query

Use viz.billboard to display a single metric value with optional color-coded thresholds:

{
  "type": "widget",
  "props": {
    "title": "Total usage this month"
  },
  "content": {
    "type": "visualization",
    "id": "viz.billboard",
    "props": {
      "nrqlQueries": [
        {
          "query": "FROM Transaction SELECT count(*) SINCE 1 month ago",
          "accountIds": [1234567]
        }
      ],
      "thresholdsWithSeriesOverrides": {
        "thresholds": [
          { "to": 200, "severity": "success" },
          { "from": 200, "to": 500, "severity": "warning" },
          { "from": 500, "severity": "critical" }
        ]
      },
      "facet": { "showOtherSeries": false },
      "platformOptions": { "ignoreTimeRange": false },
      "chartStyles": { "lineInterpolation": "linear" }
    }
  }
}

Sample request

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -H 'NewRelic-Entity: {"name": "My awesome notebook"}' \
>  -d '{
$    "version": "1",
$    "blocks": []
$  }'

Sample response

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 1
  }
}

Importante

Save the entityGuid from the response. You'll need it for reading, updating, and deleting the notebook.

Retrieves the latest content of a notebook.

Endpoint

GET /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Request parameters

Parameter	Location	Data type	Is it required?	Description
`orgId`	Path	String	Yes	Your New Relic organization ID.
`entityGuid`	Path	String	Yes	The notebook entity GUID.
`Api-Key`	Header	String	Yes	Your User API key.

Sample request

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Sample response

{
  "type": "declarative",
  "version": 1,
  "content": [
    {
      "type": "container",
      "props": {
        "layout": "stack"
      },
      "content": [
        {
          "type": "widget",
          "props": {},
          "content": {
            "type": "visualization",
            "id": "viz.billboard",
            "props": {
              "nrqlQueries": [
                {
                  "query": "FROM PageView SELECT count(*) SINCE 3 days ago",
                  "accountIds": [1]
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Creates a new version of an existing notebook by overwriting the content. The previous version is retained for up to 1 day (see Retrieve previous versions).

Endpoint

POST /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Request parameters

Parameter	Location	Data type	Is it required?	Description
`orgId`	Path	String	Yes	Your New Relic organization ID.
`entityGuid`	Path	String	Yes	The notebook entity GUID.
`Api-Key`	Header	String	Yes	Your User API key.
`Content-Type`	Header	String	Yes	Must be `application/json`.
Request body	Body	JSON	Yes	Updated notebook content.

Sample request

bash

$curl -X POST \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>  -H 'Content-Type: application/json' \
>  -d '{
$    "type": "declarative",
$    "version": 1,
$    "content": [
$      {
$        "type": "container",
$        "props": {
$          "layout": "stack"
$        },
$        "content": [
$          {
$            "type": "widget",
$            "props": {
$              "title": ""
$            },
$            "content": {
$              "type": "visualization",
$              "id": "viz.billboard",
$              "props": {
$                "nrqlQueries": [
$                  {
$                    "query": "FROM PageView SELECT count(*) SINCE 2 days ago",
$                    "accountIds": [1]
$                  }
$                ]
$              }
$            }
$          }
$        ]
$      }
$    ]
$  }'

Sample response

{
  "entityGuid": "<YOUR_ENTITY_GUID>",
  "blobId": "<YOUR_BLOB_ID>",
  "blobVersionEntity": {
    "entityGuid": "<YOUR_ENTITY_GUID>",
    "version": 2
  }
}

Deletes a notebook and its content.

Endpoint

DELETE /v1/e/organizations/{orgId}/Notebooks/{entityGuid}

Request parameters

Parameter	Location	Data type	Is it required?	Description
`orgId`	Path	String	Yes	Your New Relic organization ID.
`entityGuid`	Path	String	Yes	The notebook entity GUID to delete.
`Api-Key`	Header	String	Yes	Your User API key.

Sample request

bash

$curl -X DELETE \
>  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/Notebooks/YOUR_ENTITY_GUID \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Sample response

Returns HTTP 204 No Content on successful deletion.

Notebook versions are retained for 1 day. To recover a previous revision, first list recent versions via NRQL, then fetch the specific blob.

Step 1 — List the last 5 versions

Run this NRQL query in the query builder to gather the blob IDs and timestamps for the last 5 changes:

FROM Entity
SELECT uniques(tuple(updatedAt, content.id))
WHERE id = '<entity guid>'
SINCE 1 day ago
LIMIT 5

Step 2 — Retrieve a specific version

Use the content.id from the NRQL result to fetch that version's content:

bash

$curl -X GET \
>  https://blob-api.service.newrelic.com/v1/blobs/<content.id> \
>  -H 'Api-Key: NRAK-YOUR-API-KEY'

Entity operations (NerdGraph)

Entity-level operations such as listing, renaming, and tagging use NerdGraph rather than the Blob Storage API.

List all notebooks

query listAllNotebooks {
  actor {
    entityManagement {
      entitySearch(query: "type='NOTEBOOK'") {
        entities {
          id
          name
        }
      }
    }
  }
}

Dica

Entity creation is fully transactional, so a notebook is immediately available via the API. However, if you list notebooks through the legacy actor.entitySearch query, there may be a short propagation delay between creation and the notebook appearing in list results.

Rename a notebook

mutation changeNotebookName {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: { name: "<new name>" }
  ) {
    entity {
      name
    }
  }
}

Update notebook tags

Importante

Tag updates are a replace operation. You must include the complete set of tags, even ones that aren't changing — any tag omitted from the mutation will be removed.

mutation updateNotebookTags {
  entityManagementUpdateNotebook(
    id: "<entity guid>"
    notebookEntity: {
      tags: [
        { key: "<key>", values: "<value>" }
        { key: "<key>", values: "<value>" }
      ]
    }
  ) {
    entity {
      name
      tags {
        key
        values
      }
    }
  }
}

Retrieve your organization ID

You'll need your organization ID for all Blob Storage API calls:

query getOrgId {
  actor {
    organization {
      id
    }
  }
}

Best practices

Store entity GUIDs: Save the entityGuid returned from create operations. You'll need it for reading, updating, and deleting notebooks.
Validate JSON before upload: Ensure your notebook payload is valid JSON and conforms to the version schema before sending.
Use descriptive names: Notebook names must be unique within an organization, so choose names that clearly indicate purpose (for example, prod-checkout-investigation rather than notebook-1).
Include all tags on update: Tag updates replace the full tag set. Always read existing tags before mutating.
Recover quickly: Version history is retained for only 1 day. If you need long-term history, archive notebook content to your own storage on every update.
Secure your API key: Never expose your User API key in client-side code or public repositories.
Check HTTP status codes: The API returns 2xx for successful operations, 404 for not found, and other status codes for errors.

Common error responses

Status code	Description	Solution
`400 Bad Request`	Invalid request parameters, malformed JSON in body or `NewRelic-Entity` header, or notebook name already exists in this organization	Verify request format, header values, and that the notebook name is unique within your organization
`401 Unauthorized`	Missing or invalid API key	Check that your User API key is valid and included in the `Api-Key` header
`404 Not Found`	Notebook or version not found	Verify the entity GUID is correct
`415 Unsupported Media Type`	Incorrect `Content-Type` header	Use `Content-Type: application/json`

Additional resources

Notebooks overview — How to use Notebooks in the New Relic UI
Introduction to NerdGraph — GraphQL API reference
Blob Storage API for agent configurations — Sister API used by Fleet Control
New Relic API keys — Key types and management

Using the Blob Storage API for notebooks

Public preview

Importante

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Authentication

Dica

Base endpoint

Notebook content operations

Read notebook content

Update notebook content

Delete notebook

Retrieve previous versions

Entity operations (NerdGraph)

List all notebooks

Dica

Rename a notebook

Update notebook tags

Importante

Retrieve your organization ID

Best practices

Common error responses

Additional resources

Prerequisites