Agent Configuration Retrieval API

Authentication and Authorization

Request Body Structure

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

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

Field Descriptions

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).

Response Structure

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

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

Response Field Descriptions

Response Patterns and Examples

All agents have configs:

{
  "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:

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

Partial file matches:

{
  "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" }
    ]
  }
}

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 allowed and deduplicated.

File Name Validation (if provided): max 20 names, non-null, non-empty, no duplicates, case-sensitive.

Agent Type Validation: Must be a supported type listed above.

Error Responses

All error responses include errorCode and refCode for troubleshooting:

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

Examples

Retrieve all configuration files from Smart Agents:

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"
  }'

{
  "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": []
  }
}

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

Related APIs

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

API Evolution and Future Enhancements

Support and Feedback