canonical: https://jentic.com/apis/contrastsecurity.com/contrastsecurity

# Contrastsecurity Contrast Agent Dashboard API

Jentic publishes the only available OpenAPI specification for Contrast Agent Dashboard API, keeping it validated and agent-ready. The Contrast Agent Dashboard API exposes the inventory of Contrast Security agents deployed across an organisation's applications, servers, and hostnames, plus the effective configuration that each agent is running. Authentication uses both an API-Key header and a separate Authorization header, with the base URL configurable per Contrast instance for SaaS or hosted deployments.

## For AI agents

Inventory Contrast Security agents across applications and servers and inspect each agent's effective configuration. Authenticate with Contrast API-Key plus an Authorization header.

## Scope

Does not handle vulnerability findings, attack traces, or policy management - use for Contrast agent inventory and effective-configuration reads only.

## Capabilities

- List agents deployed in a Contrast organisation with grouping by application, server, or hostname
- Read the latest agent versions available for upgrade planning
- Retrieve a specific agent instance's status on a specific application
- Inspect the effective configuration in force for an agent on an application
- Identify configuration values that have been overridden from defaults
- Enumerate hostnames in the server inventory to map agents to physical or virtual hosts

## Use cases

### Agent Coverage and Drift Audit

Security operations teams use the Agent Dashboard API to confirm that every production application in scope is reporting a Contrast agent and that the deployed agent version is within policy. Endpoints group agents by application, server, and hostname to surface coverage gaps and drift. This gives auditors a programmatic answer to 'is Contrast running everywhere we expect?' rather than a manual spreadsheet.

Example prompt: GET `/api/v4/organizations/{organizationId}/agents/applications-group-by`, then GET `/api/v4/organizations/{organizationId}/agents/latest-versions`, and report applications running an agent version older than the latest

### Configuration Override Review

Application security engineers review which Contrast agents have configuration values overridden from defaults - a common source of detection gaps when teams disable rules. The effective-config and overridden endpoints make this review automated rather than per-application clicking, and the result feeds change-control records for each application.

Example prompt: GET `/api/v4/organizations/{organizationId}/agents/{agentReportingInstanceId}/applications/{applicationId}/effective-config/overridden` for each agent and flag any agents with disabled detection rules

### Hostname Inventory Mapping

Infrastructure teams cross-reference the Contrast server inventory with their CMDB to ensure each running host has a known owner. GET `/api/v4/organizations/{organizationId}/servers/hostnames` returns the hostnames Contrast is reporting from, which can be diffed against CMDB data to find rogue hosts or hosts missing the agent. This avoids relying on agent self-reports alone.

Example prompt: GET `/api/v4/organizations/{organizationId}/servers/hostnames` and join the result against a CMDB export to flag hosts present in CMDB but missing in Contrast

### AI Agent SecOps Helper via Jentic

An AI agent supporting security operations uses Jentic to answer questions about Contrast deployment without engineers logging into the dashboard. The agent searches Jentic for 'list contrast agents', loads the schema, and queries the organisation's agents and effective config. Through Jentic the API-Key and Authorization headers are stored in your Jentic One instance and never enter the agent's context.

Example prompt: Search Jentic for 'list contrast security agents', execute with the organizationId, and return a table of agents with their version and reporting host

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v4/organizations/{organizationId}/agents` | List agents in an organisation |
| GET | `/api/v4/organizations/{organizationId}/agents/latest-versions` | Get latest available agent versions |
| GET | `/api/v4/organizations/{organizationId}/agents/applications-group-by` | Group agents by application |
| GET | `/api/v4/organizations/{organizationId}/agents/servers-group-by` | Group agents by server |
| GET | `/api/v4/organizations/{organizationId}/agents/hostnames-group-by` | Group agents by hostname |
| GET | `/api/v4/organizations/{organizationId}/agents/{agentInstanceId}/applications/{applicationId}` | Read a specific agent instance on an application |
| GET | `/api/v4/organizations/{organizationId}/agents/{agentReportingInstanceId}/applications/{applicationId}/effective-config` | Read effective agent configuration |
| GET | `/api/v4/organizations/{organizationId}/servers/hostnames` | List hostnames in the server inventory |

## Key resources

- **Agents** — Contrast agent instances reporting from applications, with grouping endpoints by application, server, and hostname
- **Agent Versions** — Latest agent versions available across language runtimes, used to detect drift
- **Effective Config** — Per-agent effective configuration including overridden values
- **Server Inventory** — Hostnames Contrast is reporting from, used to cross-check infrastructure inventories

## Why Jentic

- **Setup:** Wiring the Contrast Agent Dashboard API by hand means sending both the API-Key and Authorization headers, pointing at your own Contrast instance host rather than a fixed one, and mapping the agent inventory reads yourself. Through Jentic you install once, import the Contrast Agent Dashboard API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Contrast puts the organization id in the URL path (`/api/v4/organizations/{organizationId}/agents`), so a rule can pin your agent to one organization and nothing else. Since this is a read-only agent and configuration surface, the agent can only inventory agents and read their effective configuration, with nothing to modify or delete.
- **Credential handling:** Your Contrast API-Key and Authorization credentials are stored once, encrypted, by your own Jentic One instance and injected into the request headers at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Contrast agents in an organization' or 'read an agent's effective configuration', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Snyk API** — Snyk focuses on SCA and IaC scanning rather than runtime IAST agents.
- **SonarCloud API** — SonarCloud provides static code analysis rather than runtime application protection.
- **Rapid7 API** — Rapid7 covers vulnerability management at the network and host layer.
- **Tenable Nessus API** — Nessus scans hosts for vulnerabilities, complementing Contrast's runtime application view.

## FAQ

### Why is there no official OpenAPI spec for Contrast Agent Dashboard API?

Contrast Security publishes API documentation at docs.contrastsecurity.com but does not host a stable OpenAPI 3 file at a permanent URL. Jentic generates and maintains this spec so that AI agents and developers can call Contrast Agent Dashboard API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Contrast Agent Dashboard API use?

Each request must include both a Contrast API-Key header and an Authorization header containing the user authentication value. Through Jentic both credentials are held in your Jentic One instance and applied at call time, so the agent never sees the raw API key or auth token.

### Can I list deployed Contrast agents with the Contrast Agent Dashboard API?

Yes. GET `/api/v4/organizations/{organizationId}/agents` lists agents in the organisation and the applications-group-by, servers-group-by, and hostnames-group-by endpoints provide aggregate views suitable for coverage dashboards.

### What are the rate limits for the Contrast Agent Dashboard API?

Contrast Security applies per-organisation rate limits sized to the customer's plan; precise limits are documented in the Contrast API reference and enforced with HTTP 429. Through Jentic, retries with exponential backoff are handled at the SDK level so transient throttling does not surface to agent code.

### How do I check effective agent configuration with the Contrast Agent Dashboard API through Jentic?

Run `jentic.search('get contrast agent effective configuration')`, load the operation, and execute with organizationId, agentReportingInstanceId, and applicationId. Jentic resolves this to GET `/api/v4/organizations/{organizationId}/agents/{agentReportingInstanceId}/applications/{applicationId}/effective-config.`

### Does the Contrast Agent Dashboard API support self-hosted instances?

Yes. The base URL is templated as https://{baseUrl} with a default of app.contrastsecurity.com but can be set to any Contrast instance hostname (Enterprise on-premises or hosted). Configure the baseUrl variable to point at your Contrast deployment.

### Can I limit what my agent is allowed to do with the Contrast Agent Dashboard API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The organization id sits in the URL path (`/api/v4/organizations/{organizationId}/agents`), so you can pin the agent to a single organization and no other. This API is read-only, so the agent can only inventory agents and read their effective configuration, with no operations that modify or delete anything.