Using Blob Storage API for agent configurations

The Blob Storage API is a New Relic service designed for uploading and managing files in your account. NerdGraph is optimized for structured data queries and mutations, so the Blob Storage API is used for operations that involve file content transfer and versioning.

Within Fleet Control, the Blob Storage API manages agent configurations—handling creation, versioning, content retrieval, and deletion of configuration files.

Prerequisites

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

Authentication

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

Generate an API key:

1. Navigate to one.newrelic.com
2. Click on your name in the bottom-left corner
3. Select API Keys
4. Create a User key (not Browser or License key)

Include in request headers:

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

Base endpoint

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

For EU region accounts, use:

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

Agent configuration operations

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

$
curl -X POST \
>
  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/AgentConfigurations \
>
  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>
  -H 'Content-Type: application/x-yaml' \
>
  -H 'NewRelic-Entity: {"name": "Production Infra Config", "agentType": "NRInfra", "managedEntityType": "HOST"}' \
>
  -d 'license_key: YOUR_LICENSE_KEY
$
log:
$
  level: info
$
  forward: true
$
integrations:
$
  - name: nri-docker
$
    enabled: true'

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

POST /v1/e/organizations/{orgId}/AgentConfigurations/{parentConfigurationId}

$
curl -X POST \
>
  https://blob-api.service.newrelic.com/v1/e/organizations/YOUR_ORG_ID/AgentConfigurations/<YOUR_ENTITY_GUID> \
>
  -H 'Api-Key: NRAK-YOUR-API-KEY' \
>
  -H 'Content-Type: application/x-yaml' \
>
  -d 'license_key: YOUR_LICENSE_KEY
$
log:
$
  level: debug
$
  forward: true
$
integrations:
$
  - name: nri-docker
$
    enabled: true
$
  - name: nri-nginx
$
    enabled: true'

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

GET /v1/e/organizations/{orgId}/AgentConfigurationVersions/{configurationVersionId}

GET /v1/e/organizations/{orgId}/AgentConfigurations/{configurationId}

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

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

license_key: YOUR_LICENSE_KEY
log:
  level: info
  forward: true
integrations:
  - name: nri-docker
    enabled: true

GET /v1/e/organizations/{orgId}/AgentConfigurations/{configurationId}/versions

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

{
  "versions": [
    {
      "entity_guid": "<YOUR_ENTITY_GUID_1>",
      "blob_id": "<YOUR_BLOB_ID_1>",
      "version": "1",
      "timestamp": "2024-01-01T00:00:00Z"
    },
    {
      "entity_guid": "<YOUR_ENTITY_GUID_2>",
      "blob_id": "<YOUR_BLOB_ID_2>",
      "version": "2",
      "timestamp": "2024-01-02T00:00:00Z"
    }
  ],
  "cursor": null
}

DELETE /v1/e/organizations/{orgId}/AgentConfigurations/{configurationId}

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

DELETE /v1/e/organizations/{orgId}/AgentConfigurationVersions/{configVersionGuid}

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

Best practices

• Store entity GUIDs: Save the entityGuid returned from create operations. You'll need these for versioning, retrieving, and deletion operations.
• Version incrementally: Create new versions for configuration changes rather than deleting and recreating configurations.
• Use descriptive names: Configuration names should clearly indicate their purpose and target environment.
• Validate YAML: Ensure your configuration content is valid YAML before uploading.
• Verify agent type compatibility: Ensure your agent type is compatible with the managed entity type (HOST or KUBERNETESCLUSTER).
• 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

Additional resources

• NerdGraph Fleet Control Tutorial - For managing fleets and deployments
• Fleet Control CLI - Command-line interface built on these APIs
• Fleet Control Overview
• New Relic API Keys