Agent Configuration Deployment API

API Overview

Endpoint POST /controller/rest/agent-management/v2/configuration/deploy
Purpose Deploy configuration files to multiple AppDynamics agents simultaneously
Content-Type application/json
Response Format application/json
Rate Limit 10 requests per minute per account
Note: Fleet Management Service currently supports only the SMART_AGENT agent type and supports the ld_preload.json configuration file. Any deployment request for other agent types or configuration files will be rejected by the Fleet Management service, even if the API validates and accepts the request.

Authentication and Authorization

Note: Agent Management Admin role is a required permis. This is a privileged operation that modifies agent configurations. Your user account must have the Agent Management Admin role to use this API.
Warning: If you receive a 403 Forbidden error with code "auth-1", contact your AppDynamics administrator to request Agent Management Admin permissions.

Request Body Structure

The request body must be a JSON object with the following fields:

JSON 
{
  "agentInstanceIds": ["string"],
  "agentType": "enum",
  "configFiles": [
    {
      "fileName": "string",
      "fileFormat": "string",
      "fileContent": "string",
      "targetPath": "string (optional)"
    }
  ],
  "scheduledTs": "number (optional)",
  "description": "string (optional)"
}

Field Descriptions

Field Type Required Description Constraints
agentInstanceIds Array of Strings Yes List of agent instance IDs to deploy configuration to Min: 1 agent; Max: 1000 agents; All agents must be of the same type
agentType Enum Yes Type of agents receiving the configuration See Supported Agent Types section
configFiles Array of Objects Yes Configuration files to deploy Min: 1 file; Max: 10 files; All agents receive the same files
scheduledTs Long No Unix timestamp in milliseconds for scheduled deployment If null or past: deploys immediately; If future: schedules deployment
description String No Human-readable description of this deployment Free-text field for documentation purposes

Config File Object Structure

Field Type Required Description Constraints
fileName String Yes Name of the configuration file Cannot be blank; Used for identification
fileFormat String Yes Format of the configuration file See Supported File Formats section
fileContent String Yes Raw content of the configuration file Cannot be blank; Max size: 100KB (102,400 bytes); Must be valid for specified format
targetPath String No Full path where file should be placed on agent If null: auto-resolved from agent properties; If specified: absolute path on agent machine

Supported Agent Types

The agentType field accepts the following values:

APP_AGENT: Java Application Agent

MACHINE_AGENT: Machine Agent (Standalone or Server Visibility)

DB_AGENT: Database Agent

DOT_NET_APP_AGENT: .NET Application Agent

PHP_APP_AGENT: PHP Application Agent

NODEJS_APP_AGENT: Node.js Application Agent

PYTHON_APP_AGENT: Python Application Agent

NATIVE_WEB_SERVER: Native Web Server Agent

SMART_AGENT: Smart Agent

Warning: Current Limitation: Fleet Management service currently processes deployments for SMART_AGENT only. Other agent types will be rejected.

Supported File Formats

The fileFormat field accepts the following values:

json: JSON configuration files

yaml or yml: YAML configuration files

xml: XML configuration files

properties: Java properties files

txt or text: Plain text files

Warning: The API validates that file content matches the declared format. For example, if you specify fileFormat as "json", the fileContent must contain valid JSON. Invalid format will result in a 400 Bad Request error.

Success Response (200 OK)

On success, the API returns a Task object representing the deployment operation:

JSON 
{
  "id": 12345,
  "name": "Config Deployment Task",
  "type": "CONFIG_DEPLOYMENT",
  "triggerTs": 1704556800000,
  "createdBy": 1001,
  "createTs": 1704556785000,
  "modifiedBy": 1001,
  "modifyTs": 1704556785000,
  "accountId": 500,
  "profileId": 0,
  "deployments": [
    {
      "id": 67890,
      "agentInstanceId": "agent-123",
      "status": "PENDING",
      "taskId": 12345
    }
  ]
}

Response Field Descriptions

Field Description
id Unique task ID - use this to track deployment status
type Task type (always "CONFIG_DEPLOYMENT" for this API)
triggerTs Timestamp when deployment will/did execute
deployments Array of individual agent deployments
deployments[].id Unique deployment ID for this specific agent
deployments[].agentInstanceId Agent that will receive the configuration
deployments[].status Current status: PENDING, IN_PROGRESS, COMPLETED, or FAILED
Tip: Tracking Deployment Status: Use the returned id to query deployment status through other Agent Management APIs. Each agent in the request will have a corresponding entry in the deployments array.

Validation Rules and Constraints

Agent Validation:

- Agent count: Between 1 and 1,000 agents per request

- Agent IDs: Cannot be null, empty, or contain blank strings

- Agent type: Must be one of the supported types listed above

Configuration File Validation:

- File count: Between 1 and 10 files per request

- File size: Each file limited to 100KB (102,400 bytes)

- File name: Cannot be null or blank

- File format: Must be one of the supported formats

- File content: Must be valid according to the declared format

Format-Specific Validation:

- JSON: Content must be valid, parseable JSON

- YAML/YML: Content must be valid YAML syntax

- XML: Content must be well-formed XML (with security protections against XXE attacks)

- Properties: Content must follow Java properties file format

- TXT/Text: No format validation (any text accepted)

Warning: XML files are parsed with strict security settings to prevent XML External Entity (XXE) attacks and XML bomb attacks. If your XML contains external entity references or DOCTYPE declarations, it will be rejected.

Error Response Format

JSON 
{
  "errorCode": "validation-1",
  "message": "Detailed error message explaining what went wrong",
  "refCode": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Common Error Scenarios

HTTP Status Error Code Description Resolution
400 Bad Request validation-1 Request validation failed Check error message for details; fix validation issues
403 Forbidden auth-1 Insufficient permissions Contact your administrator for role assignment
429 Too Many Requests rate-limit-1 Rate limit exceeded Wait and retry after a minute
500 Internal Server Error server-1 Server error occurred Contact AppDynamics support with the refCode
Tip: Every error response includes a unique refCode. When contacting support, provide this code - it allows engineers to locate the exact request in server logs for faster troubleshooting.

Examples

Example 1: Deploy ld_preload.json to Smart Agents (Currently Supported)

Deploy the ld_preload.json configuration file to 3 Smart Agents immediately.

JSON 
curl -X POST "https://your-controller.saas.appdynamics.com/controller/rest/agent-management/v2/configuration/deploy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "agentInstanceIds": [
      "smart-agent-prod-001",
      "smart-agent-prod-002",
      "smart-agent-prod-003"
    ],
    "agentType": "SMART_AGENT",
    "configFiles": [
      {
        "fileName": "ld_preload.json",
        "fileFormat": "json",
        "fileContent": "{\"version\":\"1.0\",\"libraries\":[\"/opt/appdynamics/libappdynamics.so\",\"/usr/lib/libcustom.so\"],\"environment\":{\"LD_PRELOAD_ENABLED\":\"true\"}}",
        "targetPath": "/opt/appdynamics/smart-agent/conf/ld_preload.json"
      }
    ],
    "description": "Deploy LD_PRELOAD configuration for instrumentation on Smart Agents"
  }'
JSON 
{
  "id": 15234,
  "name": "Config Deployment - 3 agents",
  "type": "CONFIG_DEPLOYMENT",
  "triggerTs": 1704556800000,
  "createdBy": 1001,
  "createTs": 1704556785000,
  "modifiedBy": 1001,
  "modifyTs": 1704556785000,
  "accountId": 500,
  "profileId": 0,
  "deployments": [
    {
      "id": 45001,
      "agentInstanceId": "smart-agent-prod-001",
      "status": "PENDING",
      "taskId": 15234
    },
    {
      "id": 45002,
      "agentInstanceId": "smart-agent-prod-002",
      "status": "PENDING",
      "taskId": 15234
    },
    {
      "id": 45003,
      "agentInstanceId": "smart-agent-prod-003",
      "status": "PENDING",
      "taskId": 15234
    }
  ]
}
Note: The fileContent field contains the JSON as an escaped string. All quotes inside the JSON must be properly escaped when embedded in the outer JSON request.
Tip: This is the only currently supported configuration by the Fleet Management service.

Troubleshooting Guide

Fleet Management service does not support configuration deployment for agent type...

Cause: Attempting to deploy configuration to an agent type other than SMART_AGENT.

Solution: Change your request to target Smart Agents only.

Fleet Management service only supports deployment of ld_preload.json configuration file

Cause: Attempting to deploy a configuration file other than ld_preload.json.

Solution: Ensure your fileName field is exactly "ld_preload.json".

Agent instance IDs cannot be null or empty

Cause: agentInstanceIds array is missing, empty, or contains blank/null values.

Solution: Ensure the array has at least one agent ID and no empty values.

File content size exceeds maximum allowed size

Cause: One or more configuration files exceed the 100KB limit.

Solution: Reduce file size or split into multiple files.

File 'config.json' has invalid JSON format: Unexpected character

Cause: File content doesn't match declared format or contains syntax errors.

Solution: Validate content independently before sending.

Rate limit exceeded

Cause: More than 10 deployment requests made within 60 seconds.

Solution: Wait and retry after a minute or batch deployments.

File deploys successfully but doesn't appear on agent

Cause: targetPath may be incorrect, or agent lacks permissions.

Solution: Verify path exists and is writable by agent.

Best Practices

Verify Agent Type and File Name: Target SMART_AGENT with ld_preload.json file only.

Batch Operations: Deploy to multiple Smart Agents in a single request.

Use Scheduled Deployments: Schedule deployments during maintenance windows.

Include Descriptive Metadata: Always populate the description field.

Validate Before Deploying: Test configuration on a single agent before large deployments.

Monitor Deployment Status: Use the returned id to monitor deployment progress.

Handle Errors Gracefully: Implement retry logic for transient failures.

Secure Your API Tokens: Treat tokens like passwords.

Keep Reference Codes: Log refCode from error responses for troubleshooting.

Plan for Future Expansion: Build integration to support additional types/files when available.

GET /controller/rest/agent-management/v2/tasks/yourTaskId: Check deployment status by task ID.

POST /controller/rest/agent-management/v2/configuration/deploy/multipart: Alternative endpoint for uploading files without JSON escaping.

POST /controller/rest/agent-management/v2/configuration/retrieve: Retrieve current configuration files from agents.

Support and Feedback

Note: Need Help? If you encounter issues not covered in this documentation: 1. Check the error refCode and message in the response. 2. Review the Troubleshooting Guide above. 3. Consult agent logs on the target machines. 4. Contact AppDynamics Support with: - The complete error response including refCode. - Request payload (with sensitive data redacted). - Agent instance IDs and types. - Controller version and deployment environment.