Customer API Access

Guardimesh provides programmatic API access to your scan data, reports, and configuration. This enables integration with AI agents, SOAR platforms, CI/CD pipelines, and custom dashboards.

Overview

The Customer API provides read-only access to the same data available in the web console:

• Scan Results — Query malware findings, drift detection, and runtime anomalies
• Pod Logs — Retrieve pod metadata and inventory records
• Reports — Access aggregated analytics, coverage metrics, and trend data
• Scan Configuration — Read your current scanner configuration
• Subscription — Check tier limits and current usage

Requirements

• Subscription tier: Startup or above
• API key with console:read scope

Trial and Individual tiers can only access data through the web console UI.

---

Authentication

API requests are authenticated with a Bearer token. Create an API key with console:read scope from the web console's API Keys page.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://console.guardimesh.com/api/scans

Creating an API Key

1. Log in to the web console at https://console.guardimesh.com
2. Navigate to API Keys in the sidebar
3. Click Create API Key
4. Enter a label (e.g., "SOAR Integration")
5. Check Console read access under Permissions
6. Click Create
7. Copy the full key immediately — it is only shown once

Alternatively, create a key programmatically (requires an active session):

curl -b cookies.txt -X POST https://console.guardimesh.com/api/keys/create \
  -H "Content-Type: application/json" \
  -d '{"label": "CI Pipeline", "scopes": ["console:read"]}'

Keys can have multiple scopes. A key with ["ingestion", "console:read"] works for both scanner authentication and console data access.

---

Endpoints

Scan Results

GET /api/scans

Returns paginated scan results including malware findings, drift detection, and runtime anomalies.

Query Parameters:

Parameter	Type	Description
startDate	unix timestamp	Start of time range
endDate	unix timestamp	End of time range
limit	integer	Results per page (default: 50, max: 1000)
offset	integer	Pagination offset
cluster	string	Filter by cluster ID
namespace	string	Filter by namespace
podName	string	Filter by pod name
imageName	string	Filter by container image name
findingsOnly	"true"	Only return scans with positive findings
findingType	string	Filter: malware, drift, or runtime
orderBy	string	Sort field: starttime, namespace, podname, clusterid, username, imagename
orderDesc	"true" / "false"	Sort direction (default: descending)

Example:

# Get the 20 most recent malware findings in the production namespace
curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/scans?findingType=malware&namespace=production&limit=20"

Response:

{
  "scanResults": [
    {
      "ContainerID": "abc123def456",
      "ImageName": "nginx:1.25",
      "Namespace": "production",
      "PodName": "web-app-7d8f9c6b4-x2k9p",
      "ClusterID": "prod-us-east-1",
      "StartTime": 1716710400,
      "Results": [
        {
          "Description": "Trojan detected",
          "FilePath": "/var/tmp/payload.bin",
          "SignatureName": "Trojan.Linux.Generic",
          "ScannerName": "ClamAV",
          "ScanSource": "runtime",
          "Timestamp": 1716710400
        }
      ]
    }
  ],
  "totalCount": 142
}

Pod Logs

GET /api/pods

Returns paginated pod creation and metadata records.

Query Parameters:

Parameter	Type	Description
startDate	unix timestamp	Start of time range
endDate	unix timestamp	End of time range
limit	integer	Results per page (default: 50, max: 1000)
offset	integer	Pagination offset
cluster	string	Filter by cluster ID
namespace	string	Filter by namespace
podName	string	Filter by pod name
orderBy	string	Sort field: starttime, namespace, podname, clusterid, nodename, ownerkind, ownername
orderDesc	"true" / "false"	Sort direction

Example:

curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/pods?namespace=default&limit=10"

Response:

{
  "podLogs": [
    {
      "PodName": "web-app-7d8f9c6b4-x2k9p",
      "Namespace": "default",
      "ClusterID": "prod-us-east-1",
      "NodeName": "worker-3",
      "OwnerKind": "ReplicaSet",
      "OwnerName": "web-app-7d8f9c6b4",
      "ImageNames": ["nginx:1.25", "sidecar:latest"],
      "StartTime": 1716710400
    }
  ],
  "totalCount": 5280
}

Reports

GET /api/reports

Returns aggregated analytics including scan summaries, time series data, top findings, and coverage metrics. Requires Startup tier or above.

Query Parameters:

Parameter	Type	Description
startDate	unix timestamp	Start of reporting period
endDate	unix timestamp	End of reporting period
cluster	string	Filter by cluster ID
namespace	string	Filter by namespace
node	string	Filter by node name
bucket	string	Time series granularity: day (default), week, month

Example:

# Get last 7 days of reports with daily granularity
START=$(date -d '7 days ago' +%s)
END=$(date +%s)
curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/reports?startDate=$START&endDate=$END&bucket=day"

Response:

{
  "scanSummary": {
    "TotalScans": 15420,
    "PositiveFindings": 3,
    "UniqueContainers": 89,
    "UniquePods": 142,
    "UniqueImages": 34
  },
  "podSummary": {
    "TotalPods": 5280,
    "UniqueNamespaces": 12,
    "UniqueNodes": 5,
    "UniqueImages": 34
  },
  "scanTimeSeries": [
    {"timestamp": "2026-05-20T00:00:00Z", "count": 2180},
    {"timestamp": "2026-05-21T00:00:00Z", "count": 2245}
  ],
  "topSignatures": [
    {"name": "Trojan.Linux.Generic", "count": 2},
    {"name": "PUA.Unix.Miner", "count": 1}
  ],
  "scanCoverage": {
    "activeNodes": 5,
    "totalNodes": 5,
    "coveragePercent": 100.0,
    "lastScanTimestamp": "2026-05-27T14:30:00Z",
    "oldestGapHours": 0
  },
  "scanGaps": []
}

Filters

GET /api/filters/clusters
GET /api/filters/namespaces

Returns distinct values for use in filter dropdowns.

Example:

curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/filters/clusters"

Response:

{
  "clusters": ["prod-us-east-1", "staging-us-central-1"]
}

Scan Configuration (read-only)

GET /api/scan-config

Returns the current scanner configuration.

curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/scan-config"

Subscription Status

GET /api/subscription

Returns tier, limits, and current usage. Useful for agents to check remaining capacity.

curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/subscription"

---

Pagination

All list endpoints support cursor-based pagination via limit and offset:

# Page 1
curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/scans?limit=50&offset=0"

# Page 2
curl -H "Authorization: Bearer $API_KEY" \
  "https://console.guardimesh.com/api/scans?limit=50&offset=50"

The totalCount field in responses indicates the total number of matching records.

---

Rate Limiting

API requests are rate-limited per key based on your subscription tier:

Tier	Rate Limit
Startup	10 requests/sec
Team	10 requests/sec
Enterprise	100 requests/sec

Rate limit headers are included in every response:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1716710401

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds to wait.

---

Error Handling

All errors return a consistent JSON format:

{
  "error": "error_code",
  "message": "Human-readable description"
}

HTTP Status	Error Code	Description
401	unauthorized	Invalid or missing API key
403	forbidden	Key lacks required scope
403	tier_insufficient	Tier does not support console API
403	subscription_expired	Subscription is expired or suspended
429	rate_limited	Rate limit exceeded
500	internal_error	Server error

---

Data Retention

Query time ranges are enforced by your tier's data retention limit:

Tier	Retention
Startup	90 days
Team	180 days
Enterprise	Unlimited

Requests for data older than your retention window return empty results (not an error).

---

Python Example

import requests

API_KEY = "your-api-key-here"
BASE_URL = "https://console.guardimesh.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def get_recent_findings(hours=24):
    """Retrieve malware findings from the last N hours."""
    import time
    end = int(time.time())
    start = end - (hours * 3600)

    response = requests.get(
        f"{BASE_URL}/api/scans",
        headers=HEADERS,
        params={
            "startDate": str(start),
            "endDate": str(end),
            "findingsOnly": "true",
            "limit": 100,
        },
    )
    response.raise_for_status()
    data = response.json()
    return data["scanResults"], data["totalCount"]

def get_coverage_report():
    """Check scan coverage across all nodes."""
    import time
    end = int(time.time())
    start = end - (7 * 24 * 3600)

    response = requests.get(
        f"{BASE_URL}/api/reports",
        headers=HEADERS,
        params={"startDate": str(start), "endDate": str(end)},
    )
    response.raise_for_status()
    data = response.json()
    return data["scanCoverage"], data["scanGaps"]

# Usage
findings, total = get_recent_findings(hours=24)
print(f"Found {total} findings in the last 24 hours")

coverage, gaps = get_coverage_report()
print(f"Coverage: {coverage['coveragePercent']}% ({coverage['activeNodes']}/{coverage['totalNodes']} nodes)")
if gaps:
    print(f"Warning: {len(gaps)} scan gaps detected")

---

AI Agent Integration

The Customer API is designed to work well with AI agents and LLM-based automation tools.

Use Cases

• Automated triage: An AI agent polls for new findings and creates tickets with context
• Compliance reporting: Generate weekly security posture summaries from reports data
• Anomaly detection: Compare scan time series against baselines to alert on spikes
• Incident response: Correlate scan findings with pod metadata during investigations

Best Practices for AI Agents

1. Poll efficiently — Use findingsOnly=true to skip clean scans. Use startDate to only fetch new data since your last poll.

2. Respect rate limits — Check X-RateLimit-Remaining before making requests. Implement exponential backoff on 429 responses.

3. Use filters — Narrow queries with cluster, namespace, and findingType rather than fetching all data and filtering client-side.

4. Paginate large result sets — Use limit and offset to process data in chunks rather than requesting maximum page sizes.

5. Cache filter values — Call /api/filters/clusters and /api/filters/namespaces once and cache the results; these change infrequently.

6. Check subscription — Call /api/subscription on startup to verify your key has access and to learn your retention window.

Machine-Readable API Spec

The full OpenAPI 3.1 specification is available at:

https://docs.guardimesh.com/openapi.yaml

This can be used with OpenAPI-compatible agent frameworks to auto-generate client code.

---

Next Steps

• API Reference — Full endpoint documentation including session-based access
• Integrations — Set up webhook notifications for real-time alerts
• Subscription Tiers — Compare tier features and limits