APIs and CLI

Fleet Control provides comprehensive programmatic access through APIs and a command-line interface, enabling you to automate fleet operations, integrate with existing tooling, and manage your instrumentation at scale without relying on the UI.

Programmatic access options

Fleet Control offers three methods for programmatic access:

• NerdGraph API: For fleet management operations including creating fleets, managing members, and controlling deployments
• Blob Storage API: For agent configuration operations including creating, versioning, and retrieving configurations
• Fleet Control CLI: For interactive command-line management and automation scripts

When to use APIs vs. CLI

Understanding which access method best fits your use case will help you work more efficiently with Fleet Control.

APIs (NerdGraph + Blob Storage API)

APIs are best for:

• Automation and integration: Building Fleet Control operations into CI/CD pipelines, custom tooling, or other automated workflows
• Infrastructure as Code: Managing fleet configurations alongside your infrastructure definitions
• System-to-system integration: Connecting Fleet Control with other platforms, ticketing systems, or orchestration tools
• Complex workflows: Creating sophisticated automation that combines multiple operations or integrates with external data sources
• Programmatic access: When you need to build Fleet Control capabilities into your own applications or services

Fleet Control CLI

The CLI is best for:

• Interactive operations: Quick, human-driven tasks from the command line
• Ad-hoc management: One-off administrative operations or troubleshooting
• Terminal-based workflows: If you prefer working directly in your terminal
• Local testing: Experimenting with fleet operations before automating them
• Shell scripts: Simple sequential operations (though APIs may be better for complex automation)
• Learning and exploration: The CLI provides immediate, structured feedback that helps you understand Fleet Control operations

The CLI is built on top of the same APIs, so functionally they provide the same capabilities. The choice is about interface preference and use case: CLI for human interaction and convenience, APIs for programmatic integration and automation.

NerdGraph API (Fleet operations)

NerdGraph is New Relic's GraphQL API that provides access to Fleet Control operations for managing fleets, members, and deployments. Unlike agent configurations (which use the Blob Storage API), all fleet-level operations use NerdGraph.

Accessing the NerdGraph Explorer

The NerdGraph Explorer is an interactive GraphQL IDE where you can discover available Fleet Control APIs, build queries, and test operations.

To access the NerdGraph Explorer:

1. Navigate to the NerdGraph Explorer for your region:
   • US region: https://one.newrelic.com/nerdgraph-graphiql
   • EU region: https://one.eu.newrelic.com/nerdgraph-graphiql
2. Enter your User API Key when prompted. This launches the API explorer with access scoped to your account.
3. In the left panel, expand mutation and navigate to fleetControl to see all available Fleet Control operations.

Available Fleet Control mutations

The NerdGraph API provides the following Fleet Control mutations:

Fleet management

• fleetControlCreateFleet - Create a new fleet
• fleetControlUpdateFleet - Update an existing fleet's properties
• fleetControlDeleteFleet - Delete a fleet

Fleet member management

• fleetControlAddFleetMembers - Add managed entities to a fleet ring
• fleetControlRemoveFleetMembers - Remove managed entities from a fleet ring

Deployment management

• fleetControlCreateFleetDeployment - Create a new deployment for a fleet
• fleetControlUpdateFleetDeployment - Update an existing deployment
• fleetControlDeleteFleetDeployment - Delete a deployment
• fleetControlDeploy - Trigger a deployment to roll out to fleet rings

Authentication

All NerdGraph API requests require authentication using a New Relic User API Key. To 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 your API key in the request headers when making API calls outside the NerdGraph Explorer.

For more information on using NerdGraph, see our Introduction to NerdGraph documentation.

Blob Storage API (Agent configurations)

The Blob Storage API is a RESTful interface specifically designed for managing agent configurations within Fleet Control. This API handles all configuration-related operations, including creating configurations, versioning, retrieving content, and deletion.

Base endpoint

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

Authentication

All Blob Storage API requests require authentication via the Api-Key header with your New Relic User API Key:

Api-Key: your-user-api-key

Key operations

The Blob Storage API supports the following operations for agent configurations:

Create Agent Configuration

Creates a new agent configuration in an organization.

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

Headers required:

• Api-Key - Your User API Key
• Content-Type - application/x-yaml
• NewRelic-Entity - JSON with configuration metadata (name, agentType, managedEntityType, configurationType)

Request body: Plain text content of the agent configuration (YAML format)

Create Agent Configuration Version

Creates a new version of an existing agent configuration.

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

Headers required:

• Api-Key - Your User API Key
• Content-Type - application/x-yaml

Request body: Plain text content of the new configuration version (YAML format)

Note: The parent configuration ID is specified in the URL path. No NewRelic-Entity header is required for creating versions.

Get Configuration Version Content

Retrieves the content of a specific configuration version.

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

Headers required:

• Api-Key - Your User API Key

Response: Returns the configuration content as plain text/YAML

Delete Configuration Version

Deletes a specific configuration version.

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

Headers required:

• Api-Key - Your User API Key

Response: 2xx status for successful deletion, 404 if configuration version not found

Valid field values

When creating agent configurations, you'll need to specify valid values for certain fields:

Agent Types

The following agent types are supported:

Infrastructure Agents (for HOST and KUBERNETESCLUSTER managed entity types):

• 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

Application Agents (for APPLICATION managed entity type):

• NRJavaAgent - Java APM agent
• NRPythonAgent - Python APM agent
• NRNodeAgent - Node.js APM agent
• NRRubyAgent - Ruby APM agent
• NRDotNetAgent - .NET APM agent

Managed Entity Types

• HOST - Individual host/server entities (can only use Infrastructure Agents)
• KUBERNETESCLUSTER - Kubernetes cluster entities (can only use Infrastructure Agents)
• APPLICATION - Application entities (can only use Application Agents)

Configuration Type

• Instrumentation - Currently the only supported configuration type

Best practices

• Always check HTTP status codes: The API returns 200 for successful operations
• Store returned entity GUIDs: You'll need these for versioning and deletion operations
• Validate JSON formatting: Ensure proper JSON formatting in the NewRelic-Entity header
• Verify agent type compatibility: Ensure your agent type is compatible with the managed entity type
• Use correct Content-Type: Always use application/x-yaml for configuration content
• Secure your API Key: Never expose your User API Key in client-side code or public repositories

Fleet Control CLI

The Fleet Control CLI is a comprehensive command-line interface for managing all Fleet Control entities including fleets, configurations, deployments, members, and entity queries. The CLI provides a structured, terminal-based workflow for both interactive operations and automation.

Command hierarchy

Fleet Control commands are organized by resource type for intuitive navigation:

newrelic fleetcontrol
├── fleet                    # Fleet management
│   ├── create              # Create a new fleet
│   ├── get                 # Get fleet details
│   ├── search              # Search fleets
│   ├── update              # Update fleet
│   ├── delete              # Delete fleet(s)
│   └── members             # Manage fleet members
│       ├── add             # Add entities to ring
│       ├── remove          # Remove entities from ring
│       └── list            # List fleet members
│
├── configuration            # Configuration management
│   ├── create              # Create configuration
│   ├── get                 # Get configuration content
│   ├── delete              # Delete configuration
│   └── versions            # Manage configuration versions
│       ├── list            # List all versions
│       ├── add             # Add new version
│       └── delete          # Delete specific version
│
├── deployment               # Deployment management
│   ├── create              # Create deployment
│   ├── update              # Update deployment
│   ├── deploy              # Trigger deployment
│   └── delete              # Delete deployment
│
└── entities                 # Entity queries
    ├── get-managed         # List managed entities
    └── get-unassigned      # List available entities

Key capabilities

The Fleet Control CLI enables you to:

• Centralize agent operations: Install, monitor, configure, and update all agents and integrations from the command line
• Manage fleets: Group entities by instrumentation needs and upgrade agent versions for entire fleets
• Create and version configurations: Author agent configurations and manage multiple versions
• Control deployments: Create, update, and trigger deployments with ring-based rollouts
• Query entities: List managed and unassigned entities to understand your fleet landscape

Prerequisites

Before using Fleet Control CLI commands, you'll need:

Required environment variables:

$
# Your New Relic User API Key
$
export NEW_RELIC_API_KEY="NRAK-YOUR-API-KEY-HERE"
$

$
# Your New Relic Account ID
$
export NEW_RELIC_ACCOUNT_ID="your-account-id"
$

$
# Optional: Specify region (defaults to US)
$
export NEW_RELIC_REGION="US"  # or "EU" for European accounts

Getting your credentials:

1. API Key: Generate a User API Key from one.newrelic.com → Click your name → API Keys → Create a "User" key
2. Account ID: Find your account ID in the New Relic URL after /accounts/ or in Account settings
3. Organization ID: Most commands accept an optional --organization-id flag. If not provided, the CLI will automatically fetch your organization ID using your API credentials.

Complete CLI documentation

For getting started with the New Relic CLI including installation and setup, see the New Relic CLI repository.

For detailed Fleet Control command reference, response formats, validation rules, and troubleshooting guidance, see the Fleet Control CLI README.

The CLI documentation includes:

• Complete command reference for all operations
• Response format specifications
• Working with JSON responses using jq
• Practical workflow examples
• Validation rules and allowed values
• Troubleshooting common issues
• Flag syntax and usage patterns

Getting started with programmatic access

To begin using Fleet Control programmatically:

1. Generate a User API Key from your New Relic account settings
2. Identify your Account ID and Organization ID from the New Relic platform
3. Choose your access method:
   • Use the NerdGraph Explorer to explore fleet operations interactively
   • Review the Blob Storage API operations for configuration management
   • Install and configure the Fleet Control CLI for terminal-based workflows
4. Start with read operations to familiarize yourself with the data structures (search fleets, list entities, get configurations)
5. Build automation gradually by combining operations into scripts or workflows

For additional help with APIs, see our Introduction to NerdGraph documentation and API Keys documentation.