---
title: Using Blob Storage API for agent configurations
source: https://docs.newrelic.com/docs/apis/intro-apis/blob-storage-api
---

> #### ⚠️ FEATURE AVAILABILITY
>
> Fleet Control for Kubernetes clusters is generally available (GA). Support for managing agents on Linux and Windows hosts is currently in public preview.
>
> For a complete list of supported agents and their environments, see our [agent type compatibility documentation](https://docs.newrelic.com/docs/new-relic-control/agent-control/agent-types).
>
> The public preview feature is provided pursuant to our [pre-release policies](https://docs.newrelic.com/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy).

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.

> #### ⚠️ IMPORTANT
>
> Agent configurations in Fleet Control use the **Blob Storage API**, not NerdGraph. For fleet, member, and deployment operations, see the **NerdGraph tutorial**.

## Prerequisites

-   A [New Relic account](https://newrelic.com/signup) with a User API key
-   Your New Relic Organization ID
-   Appropriate [permissions](https://docs.newrelic.com/docs/new-relic-control/fleet-control/overview#required-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](https://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
```

For JP region accounts, use:

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

## Agent configuration operations

**Create agent configuration**

Creates a new agent configuration in an organization.

### Endpoint

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

### Request parameters

| Parameter         | Location | Data type   | Is it required? | Description                                                                         |
| ----------------- | -------- | ----------- | --------------- | ----------------------------------------------------------------------------------- |
| `orgId`           | Path     | String      | Yes             | Your New Relic organization ID.                                                     |
| `Api-Key`         | Header   | String      | Yes             | Your User API key.                                                                  |
| `Content-Type`    | Header   | String      | Yes             | Must be `application/x-yaml`.                                                       |
| `NewRelic-Entity` | Header   | JSON string | Yes             | JSON object containing configuration metadata (name, agentType, managedEntityType). |
| Request body      | Body     | Plain text  | Yes             | Agent configuration content in YAML format.                                         |

### NewRelic-Entity header format

The `NewRelic-Entity` header must contain a JSON object with the following fields:

| Field               | Data type | Is it required? | Description                                                |
| ------------------- | --------- | --------------- | ---------------------------------------------------------- |
| `name`              | String    | Yes             | The configuration name.                                    |
| `agentType`         | String    | Yes             | Agent type (for example, `NRInfra`, `NRDOT`, `FluentBit`). |
| `managedEntityType` | String    | Yes             | Entity type: `HOST` or `KUBERNETESCLUSTER`.                |

### Supported agent types

**Infrastructure agents** (for HOST and KUBERNETESCLUSTER):

-   `NRInfra` - New Relic Infrastructure agent
-   `NRDOT` - New Relic Distribution of OpenTelemetry Collector
-   `FluentBit` - Fluent Bit logging agent
-   `NRPrometheusAgent` - Prometheus agent
-   `PipelineControlGateway` - Pipeline Control gateway
-   `NRApmOperator` - APM Operator for Kubernetes
-   `NReBPFAgent` - eBPF agent

### Sample request

```bash
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'
```

### Sample response

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

**Important:** Save the `entityGuid` from the response. You'll need it for versioning, retrieving, and deleting the configuration.

**Create configuration version**

Creates a new version of an existing agent configuration.

### Endpoint

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

### Request parameters

| Parameter               | Location | Data type  | Is it required? | Description                                         |
| ----------------------- | -------- | ---------- | --------------- | --------------------------------------------------- |
| `orgId`                 | Path     | String     | Yes             | Your New Relic organization ID.                     |
| `parentConfigurationId` | Path     | String     | Yes             | The parent configuration entity GUID.               |
| `Api-Key`               | Header   | String     | Yes             | Your User API key.                                  |
| `Content-Type`          | Header   | String     | Yes             | Must be `application/x-yaml`.                       |
| Request body            | Body     | Plain text | Yes             | Updated agent configuration content in YAML format. |

### Sample request

```bash
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'
```

### Sample response

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

**Get configuration content**

Retrieves the content of a specific configuration version.

### Endpoint

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

To retrieve the latest version of a configuration, use:

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

### Request parameters

| Parameter                | Location | Data type | Is it required? | Description                                                      |
| ------------------------ | -------- | --------- | --------------- | ---------------------------------------------------------------- |
| `orgId`                  | Path     | String    | Yes             | Your New Relic organization ID.                                  |
| `configurationVersionId` | Path     | String    | Yes             | The configuration version entity GUID.                           |
| `Api-Key`                | Header   | String    | Yes             | Your User API key.                                               |
| `version`                | Query    | Integer   | No              | Specific version number to retrieve (for example, `?version=1`). |

### Sample request (specific version)

```bash
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'
```

### Sample request (latest version)

```bash
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'
```

### Sample response

Returns the configuration content as plain text (YAML):

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

**List configuration versions**

Retrieves all versions of a configuration.

### Endpoint

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

### Request parameters

| Parameter         | Location | Data type | Is it required? | Description                     |
| ----------------- | -------- | --------- | --------------- | ------------------------------- |
| `orgId`           | Path     | String    | Yes             | Your New Relic organization ID. |
| `configurationId` | Path     | String    | Yes             | The configuration 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/AgentConfigurations/<YOUR_ENTITY_GUID>/versions \
  -H 'Api-Key: NRAK-YOUR-API-KEY'
```

### Sample response

```json
{
  "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 configuration**

Deletes a configuration and all its versions.

### Endpoint

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

### Request parameters

| Parameter         | Location | Data type | Is it required? | Description                              |
| ----------------- | -------- | --------- | --------------- | ---------------------------------------- |
| `orgId`           | Path     | String    | Yes             | Your New Relic organization ID.          |
| `configurationId` | Path     | String    | Yes             | The configuration 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/AgentConfigurations/<YOUR_ENTITY_GUID> \
  -H 'Api-Key: NRAK-YOUR-API-KEY'
```

### Sample response

Returns HTTP 204 No Content on successful deletion.

**Delete configuration version**

Deletes a specific configuration version.

### Endpoint

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

### Request parameters

| Parameter           | Location | Data type | Is it required? | Description                                      |
| ------------------- | -------- | --------- | --------------- | ------------------------------------------------ |
| `orgId`             | Path     | String    | Yes             | Your New Relic organization ID.                  |
| `configVersionGuid` | Path     | String    | Yes             | The configuration version 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/AgentConfigurationVersions/<YOUR_ENTITY_GUID> \
  -H 'Api-Key: NRAK-YOUR-API-KEY'
```

### Sample response

Returns HTTP 204 No Content on successful deletion.

## 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

| Status code                  | Description                                                            | Solution                                                                 |
| ---------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `400 Bad Request`            | Invalid request parameters or malformed JSON in NewRelic-Entity header | Verify request format and header values                                  |
| `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`              | Configuration or version not found                                     | Verify the entity GUID is correct                                        |
| `415 Unsupported Media Type` | Incorrect Content-Type header                                          | Use `Content-Type: application/x-yaml`                                   |

## Additional resources

-   [NerdGraph Fleet Control Tutorial](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-fleet-control-tutorial) - For managing fleets and deployments
-   [Fleet Control CLI](https://github.com/newrelic/newrelic-cli/tree/main/internal/fleetcontrol) - Command-line interface built on these APIs
-   [Fleet Control Overview](https://docs.newrelic.com/docs/new-relic-control/fleet-control/overview)
-   [New Relic API Keys](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys)