Agent Configuration Retrieval API

API Overview

Property Value
Endpoint POST /controller/rest/agent-management/v2/configuration/retrieve
HTTP Method POST (agent IDs in request body)
Purpose Retrieve configuration files from multiple agents
Content-Type application/json
Response Format application/json
Rate Limit No specific rate limit (read-only)

Authentication and Authorization

Note: Required permission: Agent Management Viewer role (or higher). This is a read-only operation for viewing agent configurations.
Note: Viewer role is sufficient for retrieval; Admin role is only required for configuration deployment.
Note: If you receive a 403 Forbidden error with code "auth-1", request the Agent Management Viewer role from your administrator.

Request Body Structure

The request body must be a JSON object structured as follows:

JSON 
{
  "agentInstanceIds": ["string"],
  "agentType": "enum",
  "configFileNames": ["string"]
}

Field Descriptions

Field Type Required Description Constraints
agentInstanceIds Array of Strings Yes Agent instance IDs to retrieve configuration from Min: 1; Max: 100; All agents must be same type; duplicates allowed (deduplicated)
agentType Enum Yes Type of agent being queried See Supported Agent Types section
configFileNames Array of Strings No Specific configuration file names to retrieve If omitted, returns all files; Max: 20; no duplicate names; case-sensitive

Supported Agent Types

agentType can be:

APP_AGENT, MACHINE_AGENT, DB_AGENT, DOT_NET_APP_AGENT, PHP_APP_AGENT, NODEJS_APP_AGENT, PYTHON_APP_AGENT, NATIVE_WEB_SERVER, SMART_AGENT

Configuration File Names

If configFileNames is omitted or empty, all configuration files are returned for each agent. If specified, only those files are returned if they exist (case-sensitive, max 20 per request, no duplicates).

Note: If some files exist and others do not, only existing files are returned. Empty arrays indicate no files found.

Response Structure

HTTP 200 OK is returned for successful requests. The response maps agent IDs to arrays of configuration files:

JSON 
{
  "configs": {
    "agent-instance-id-1": [
      {
        "fileName": "string",
        "fileFormat": "string",
        "fileContent": "string",
        "targetPath": "string"
      }
    ],
    "agent-instance-id-2": []
  }
}

Response Field Descriptions

Field Description
configs Map of agent IDs to arrays of configuration files
configs[agentId] Array of configuration file objects for the agent
fileName Name of configuration file (e.g., "ld_preload.json")
fileFormat Format of the file ("json", "yaml", "xml", "properties", "txt")
fileContent Raw content of the file as a string
targetPath Full path to the file on agent system

Response Patterns and Examples

All agents have configs:

JSON 
{
  "configs": {
    "agent-001": [
      { "fileName": "config.json", "fileFormat": "json", "fileContent": "...", "targetPath": "/path/to/config.json" }
    ],
    "agent-002": [
      { "fileName": "config.json", "fileFormat": "json", "fileContent": "...", "targetPath": "/path/to/config.json" }
    ]
  }
}

Some agents have no configs:

JSON 
{
  "configs": {
    "agent-001": [
      { "fileName": "config.json", "fileFormat": "json", "fileContent": "...", "targetPath": "/path/to/config.json" }
    ],
    "agent-002": [],
    "agent-003": []
  }
}
Note: An empty array for an agent means no config files matched or exist. This is not an error.

Partial file matches:

JSON 
{
  "configs": {
    "agent-001": [
      { "fileName": "config.json", "fileFormat": "json", "fileContent": "...", "targetPath": "/path/to/config.json" }
    ],
    "agent-002": [
      { "fileName": "config.json", "fileFormat": "json", "fileContent": "...", "targetPath": "/path/to/config.json" },
      { "fileName": "settings.yaml", "fileFormat": "yaml", "fileContent": "...", "targetPath": "/path/to/settings.yaml" }
    ]
  }
}
Note: Each agent can have a different set of configuration files, reflecting their actual state.

Validation Rules and Constraints

Agent Validation:

  • 1-100 agents per request.

  • Agent IDs must be non-null, non-empty, and exist in the system.

  • All agents must match the agentType field.

  • Duplicates are allowed.

File Name Validation (if provided):

  • maximum 20 names.

  • not null.

  • not empty

  • no duplicates

  • case-sensitive.

Agent Type Validation: Must be a supported type.

Error Responses

All error responses include errorCode and refCode for troubleshooting:

JSON 
{
  "errorCode": "string",
  "message": "Detailed error message explaining what went wrong",
  "refCode": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
HTTP Status Error Code Description Resolution
400 Bad Request validation-1 or validation-2 Request validation failed Fix validation issues as described in message
403 Forbidden auth-1 or auth-2 Insufficient permissions Request Viewer role from admin
404 Not Found not-found-1 or not-found-2 Agents not found Verify agent IDs and their existence
500 Internal Server Error server-1 or server-2 Server error occurred Contact support with refCode
Note: Always provide refCode when contacting support for efficient troubleshooting.

Examples

Retrieve all configuration files from Smart Agents:

JSON 
curl -X POST "https://your-controller.saas.appdynamics.com/controller/rest/agent-management/v2/configuration/retrieve" \
  -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"
  }'
Note: If configFileNames is omitted, all files are returned for each agent.
JSON 
{
  "configs": {
    "smart-agent-prod-001": [
      {
        "fileName": "ld_preload.json",
        "fileFormat": "json",
        "fileContent": "...",
        "targetPath": "/opt/appdynamics/smart-agent/conf/ld_preload.json"
      },
      {
        "fileName": "agent-config.yaml",
        "fileFormat": "yaml",
        "fileContent": "...",
        "targetPath": "/opt/appdynamics/smart-agent/conf/agent-config.yaml"
      }
    ],
    "smart-agent-prod-002": [
      {
        "fileName": "ld_preload.json",
        "fileFormat": "json",
        "fileContent": "...",
        "targetPath": "/opt/appdynamics/smart-agent/conf/ld_preload.json"
      }
    ],
    "smart-agent-prod-003": []
  }
}
Note: Agent-001 has two configs, Agent-002 has one, Agent-003 none. All are valid.

Troubleshooting Guide

  • Agents not found: Verify spelling, registration, and connectivity. Remove decommissioned agents.

  • Agent type mismatch: Confirm actual type and group agents by type.

  • Too many config files: Limit to 20 or split into multiple requests.

  • Duplicate file names: Ensure all file names are unique and correct case.

  • Too many agents: Limit to 100 per request or batch requests.

  • All agents return empty arrays: May be due to no configs, incorrect filters, or pending deployments. Check agent state and retry.

  • Partial results: Reflects actual agent state. Investigate as needed.

Best Practices

  • Batch queries up to 100 agents.

  • Use file filters for performance.

  • Cache results.

  • Validate agent types.

  • Audit regularly.

  • Handle errors and retries.

  • Secure tokens.

  • Log refCodes.

  • Allow for eventual consistency.

  • Use API for compliance and drift detection.

Performance Considerations

Note: Optimized for scale: Two database queries per batch of up to 100 agents. File filtering in memory. Typical response times: 1-10 agents <1s, 11-50 agents: 1-3s, 51-100 agents: 3-5s. No aggressive rate limits.

POST /controller/rest/agent-management/v2/configuration/deploy: Deploy configuration files.

POST /controller/rest/agent-management/v2/configuration/deploy/multipart: Multipart deploy.

GET /controller/rest/agent-management/v2/tasks/{taskId}: Check deployment status.

POST /controller/rest/agent-management/v2/agents/query: Query agent inventory.

Differences from Deployment API

Aspect Retrieval API Deployment API
HTTP Method POST (body contains agent list) POST
Permission Viewer (read-only) Admin (write)
Purpose Query configuration state Deploy new configurations
Rate Limiting None 10/minute
Agent Limit 100 1000
File Limit 20 10
File Size No limit 100KB/file
Response Immediate Task object (async)
Partial Results Yes N/A
Empty Results Valid (empty arrays) N/A

API Evolution and Future Enhancements

Note: The API is designed for all agent types and configuration files. New agent types and files are supported without changes to your integration.

Support and Feedback

Note: For help: Check error refCode and message, review troubleshooting, verify IDs and types, check agent status, and contact AppDynamics Support with refCode, redacted payload, agent IDs, and environment details.