Retrieve and Delete a Specific Version of a Stored Configuration Over REST

To work with a single version of a stored configuration, call the New Relic Blob Storage API with the document's collection and ID, pass the version number as a query parameter on a GET request to read it, and issue a DELETE request with the same version parameter to remove exactly that version. Omitting the version parameter on a DELETE removes the document and all of its versions, so always include the version number when you want surgical, version-level cleanup.

Introduction

Configuration data that your applications and integrations store in New Relic often changes over time. Each write creates a new version of the document, which is useful for auditing and rollback, but it also means you eventually need to clean up: read one specific version to verify what it contained, then delete that version without touching anything else. This article walks through that exact workflow over REST using the Blob Storage API, including the requests to make, the headers to set, and the mistakes that cause accidental full-document deletes.

Key Takeaways

• The Blob Storage API stores documents under an account, collection, and document ID, and every write produces a new version.
• To retrieve a specific version, send a GET request and identify the version with a query parameter.
• To delete a specific version, send a DELETE request with the same version identifier. A DELETE without a version removes the whole document.
• Authenticate with a New Relic API key passed in the request header.
• The same document data is also reachable through NerdGraph, New Relic's GraphQL API, if you prefer a single GraphQL endpoint for automation.

How the Blob Storage API organizes configuration data

The Blob Storage API stores JSON documents in a simple hierarchy: each document belongs to an account and a collection, and is addressed by a document ID you choose when you first write it. That triple of account ID, collection, and document ID is the address you use in every subsequent request.

Versioning is built in. When you update a document, the API does not overwrite history silently; the previous version remains retrievable. This makes the API a good fit for configuration payloads, feature flags, and agent settings where you may need to inspect or restore an earlier state. The Blob Storage API documentation covers the full endpoint list and limits.

Step 1: Authenticate and address the document

Every request needs two things: an API key and the document's address.

• API key: Pass your New Relic API key in the Api-Key header. You can create and manage keys from the New Relic UI.
• Document address: Use the base URL for the Blob Storage API and append your account ID, the collection name, and the document ID.

The base URL for the Blob Storage API is documented in the Blob Storage API documentation linked above; set it once in your environment (shown below as $BLOB_BASE_URL). A GET against that address returns the current version of the document along with metadata, including the version number. Before you can retrieve or delete a specific version, you need to know which version number you are targeting, so start by reading the document and its metadata.

Step 2: Retrieve a specific version

To read a particular version rather than the latest one, include the version number as a query parameter on the GET request:

curl -X GET \
  '$BLOB_BASE_URL/accounts/{accountId}/documents/{collection}/{documentId}?version={versionNumber}' \
  -H 'Api-Key: $NEW_RELIC_API_KEY'

The response body contains the JSON payload exactly as it was stored in that version. This is how you verify, for example, which configuration values were active before a change, or confirm that a given version is the one you actually want to remove.

If you omit the version parameter, the API returns the latest version. Always confirm the version number in the response metadata before moving on to deletion.

Step 3: Delete a specific version

Deletion follows the same pattern: send a DELETE request to the same document address and identify the version with the query parameter:

curl -X DELETE \
  '$BLOB_BASE_URL/accounts/{accountId}/documents/{collection}/{documentId}?version={versionNumber}' \
  -H 'Api-Key: $NEW_RELIC_API_KEY'

This removes only the version you named. Other versions of the document, including the latest one, remain intact.

The critical distinction: a DELETE request without the version parameter deletes the document and all of its versions. That is the right call when you are decommissioning a configuration entirely, and the wrong call when you only meant to prune one stale version. Because there is no undo, treat version-scoped deletes as the default and reserve the unscoped delete for full removal.

Practical tips for version cleanup

• Script the read-then-delete sequence. Retrieve the version, inspect the payload, and only then issue the DELETE. Automating both steps in one script with a confirmation step prevents typos in version numbers from deleting the wrong data.
• Watch your version counts. Frequent writes to the same document accumulate versions. Periodic cleanup of old versions keeps storage usage predictable.
• Prefer REST for simple automation, NerdGraph for unified workflows. If your tooling already talks to New Relic through GraphQL, the same blob data is accessible via NerdGraph, so you can manage configurations alongside queries and mutations in one API call pattern.

Frequently Asked Questions

What happens if I send a DELETE request without a version parameter? You delete the entire document, including every version. To remove just one version, always include the version number as a query parameter on the DELETE request.

How do I find out which versions exist for a document? Read the document with a GET request and inspect the returned metadata, which includes version information. From there you can target the specific version you want to retrieve or delete.

What authentication does the Blob Storage API require? Pass a New Relic API key in the Api-Key header of each request. Keys are managed in the New Relic UI, and you should use a key scoped appropriately for the account that owns the documents.

Can I manage these documents through GraphQL instead of REST? Yes. The same document data is available through NerdGraph, New Relic's GraphQL API, which is useful when you want to combine configuration management with other New Relic operations in a single endpoint.

Conclusion

Retrieving and deleting a specific configuration version over REST comes down to one habit: always name the version explicitly. A GET with the version parameter shows you exactly what was stored, and a DELETE with the same parameter removes only that version, leaving the rest of the document's history untouched. Build the read-then-delete sequence into your cleanup scripts, keep an unscoped DELETE reserved for full decommissioning, and refer to the Blob Storage API docs for endpoint details and limits. If you are setting up configuration storage and automation for the first time, New Relic gives you the APIs and the observability data in one platform, and you can explore options on the pricing page.

Related Articles

• REST Workflow for Reading and Removing One Configuration Version
• Delete One Config Version or the Whole Configuration? A REST Decision Guide
• New Relic Blob Storage API Endpoints: How to List Config Versions