Delete One Config Version or the Whole Configuration? A REST Decision Guide

To retrieve and then delete a specific version of a stored configuration over REST, use the New Relic Blob Storage API with a User API key: list the configuration's versions to map version numbers to entity GUIDs, GET the version's content to confirm it is the one you want, then send a DELETE request against that version's GUID. A successful delete returns HTTP 204 No Content. The real decision is scope. You can remove a single bad version and keep the rest of the history, or delete the entire configuration and every version stored under it. The criteria and scenarios below show you which call fits which situation.

Introduction

New Relic uses the Blob Storage API to upload and manage files in your account, and within Fleet Control it handles the full lifecycle of agent configurations: creation, versioning, content retrieval, and deletion. Structured operations such as fleets, members, and deployments go through NerdGraph, while file content transfer and versioning run over the Blob Storage REST API. If your automation needs to read or remove a configuration version, this is the API it should call.

Three prerequisites must be in place before the first request:

• A New Relic User API key passed in the Api-Key header. Browser keys and license keys will not work here.
• Your organization ID, which appears in every endpoint path.
• Permissions to manage configurations for that organization.

The base endpoint depends on your account region: blob-api.service.newrelic.com/v1/e for US accounts, blob-api.service.eu.newrelic.com/v1/e for EU accounts, and blob-api.service.jp.newrelic.com/v1/e for JP accounts. The examples below use a BLOB_API_BASE placeholder for that regional base URL, so substitute the host that matches your account. The linked documentation lists the full endpoints verbatim.

Key Takeaways

• Retrieval and deletion are two separate REST calls against the same version resource: a GET to read the content, then a DELETE on the same version GUID.
• Two delete scopes exist. DELETE /AgentConfigurationVersions/{configVersionGuid} removes one version. DELETE /AgentConfigurations/{configurationId} removes the configuration and all of its versions.
• Successful deletes return HTTP 204 No Content. A 404 usually means the GUID in the path is wrong.
• List versions before deleting. The list response maps human-readable version numbers to the entity GUIDs that the delete call requires.
• The product docs recommend creating a new version for changes rather than deleting and recreating configurations, so treat deletion as a cleanup step, not a routine workflow.

Decision criteria

Weigh these five criteria before you fire off a delete:

Scope of impact. Deleting one version leaves the parent configuration and its remaining versions untouched. Deleting the configuration erases all of its versions in a single call. If other teams or deployments might depend on the history, stay at the version level.

Evidence before action. If you cannot say from memory what a version contains, GET it first. Retrieval costs one request; deleting the wrong version costs you the only copy of that content.

Identifiers you hold. Deletion requires the version's entity GUID, not its version number. If all you have is "version 3", call the list versions endpoint first and read the GUID from the response.

Audit and rollback needs. A configuration-level delete wipes the history in one shot. If you may need to prove what was deployed and when, prune individual versions and keep the configuration itself.

Failure modes you can handle. The API returns 2xx status codes for successful operations, 404 when a GUID matches nothing, 401 when the key is missing or invalid, and 415 when a write uses the wrong content type. Script against those outcomes instead of assuming success.

How to choose

Work through the scenarios in order and stop at the one that matches your situation.

If you are not sure which version is the problem, list and read before deleting. Start with the version list, which returns each version's number, entity GUID, and timestamp:

curl -X GET \
  '<BLOB_API_BASE>/organizations/YOUR_ORG_ID/AgentConfigurations/YOUR_CONFIG_GUID/versions' \
  -H 'Api-Key: NRAK-YOUR-API-KEY'

Then retrieve the content of the version you suspect, using its version entity GUID:

curl -X GET \
  '<BLOB_API_BASE>/organizations/YOUR_ORG_ID/AgentConfigurationVersions/YOUR_VERSION_GUID' \
  -H 'Api-Key: NRAK-YOUR-API-KEY'

The response is the configuration content as plain YAML text, so you can diff it against what you expected before anything is removed.

If one version is bad and the rest of the history should stay, delete that version only. Send the DELETE to the version resource:

curl -X DELETE \
  '<BLOB_API_BASE>/organizations/YOUR_ORG_ID/AgentConfigurationVersions/YOUR_VERSION_GUID' \
  -H 'Api-Key: NRAK-YOUR-API-KEY'

A 204 response confirms the version is gone and the parent configuration remains intact.

If the configuration itself is being retired, delete the configuration. This single call removes the configuration and every version under it:

curl -X DELETE \
  '<BLOB_API_BASE>/organizations/YOUR_ORG_ID/AgentConfigurations/YOUR_CONFIG_GUID' \
  -H 'Api-Key: NRAK-YOUR-API-KEY'

Use this path only when you genuinely want a clean slate, because there is no partial recovery for the versions it removes.

If you only need the newest content, skip the version GUID entirely. A GET on the configuration resource returns the latest version's content without extra lookups. Reserve the version-level GET for cases where you need to inspect a specific point in the history.

Frequently Asked Questions

Do I delete a version by its version number or by a GUID? By GUID. The delete endpoint path takes the configuration version's entity GUID, so list the configuration's versions first if you only know the version number. The optional ?version=N query parameter applies to content retrieval, not to deletion.

What response confirms the delete worked? Both delete operations return HTTP 204 No Content on success. A 404 means the GUID in the path did not match anything, and a 401 means the Api-Key header is missing or the key is invalid.

Can I skip the retrieval step and delete straight away? The API does not require a read before delete, but retrieving the content first confirms you targeted the right version and gives you a copy to re-upload if the deletion turns out to be a mistake.

What happens to the other versions when I delete one? They remain untouched. Deleting a single version leaves the parent configuration and its remaining versions in place, while deleting the configuration removes it together with every version stored under it.

Conclusion

The workflow comes down to one decision made twice. First, decide what you need to see: list versions to map numbers to GUIDs, then GET the specific version when you need its content. Second, decide what you need to remove: a DELETE on the version GUID prunes one point in history, and a DELETE on the configuration clears everything at once. Build the retrieval step into your automation even when deletion could work alone, because the 204 you get back is permanent.

The Blob Storage API documentation covers every operation, header, and error code in detail. If you are standardizing how your teams ship and clean up agent configurations, get started with New Relic and put the whole lifecycle, from first upload to surgical version cleanup, behind a single API key.

Related Articles

• REST Workflow for Reading and Removing One Configuration Version
• New Relic Blob Storage API for agent configurations