API Reference

Shadow AI API

List, investigate, and resolve detections of AI services being used within your organisation outside of approved governance boundaries. Shadow AI detections are created automatically by Audital's network monitoring and behavioural analysis systems.

Last updated: 2 March 2026

Detection Lifecycle

OPEN→INVESTIGATING→RESOLVEDor DISMISSED

Resolution	Meaning
ONBOARDED	The AI usage was legitimate and has been registered with Audital as a governed model
STOPPED	The AI usage has been discontinued and is no longer observed
APPROVED_EXCEPTION	The usage is approved as a time-limited exception with documented justification
FALSE_POSITIVE	The detection was incorrect — the traffic was not AI usage

Endpoints

Method	Path	Description
GET	/shadow-ai/detections	List shadow AI detections
GET	/shadow-ai/:id	Get a single detection
PATCH	/shadow-ai/:id	Update status, assignee, or notes
GET	/shadow-ai/stats	Aggregate statistics and provider breakdown

GET/shadow-ai/detections

Returns a paginated list of shadow AI detections. Filter by status, severity, or date range.

bash

curl "https://api.audital.ai/v1/shadow-ai/detections?status=OPEN&limit=25" \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx"

json

{
  "data": [
    {
      "id": "sad_01HZABCDEF1234567890ABCD",
      "status": "OPEN",
      "severity": "HIGH",
      "detectedAt": "2026-03-02T11:34:00.000Z",
      "source": "NETWORK_TRAFFIC",
      "organisationId": "org_xyz789",
      "details": {
        "aiProvider": "OpenAI",
        "endpoint": "api.openai.com",
        "estimatedCallVolume": 1240,
        "estimatedCostUSD": 18.60,
        "firstSeenAt": "2026-02-28T09:00:00.000Z",
        "lastSeenAt": "2026-03-02T11:30:00.000Z",
        "userAgents": ["openai-python/1.13.3"],
        "internalIpRanges": ["10.0.2.x"],
        "departmentHint": "Engineering",
        "registeredWithAudital": false
      },
      "riskFactors": [
        "API calls contain potential PII (email addresses detected)",
        "No data processing agreement on file for this service",
        "Usage exceeds 1,000 calls/day threshold"
      ],
      "assignedTo": null,
      "notes": null,
      "resolvedAt": null
    }
  ],
  "pagination": {
    "total": 3,
    "limit": 25,
    "offset": 0,
    "hasMore": false
  },
  "summary": {
    "open": 3,
    "investigating": 1,
    "resolved": 12,
    "dismissed": 2
  }
}

Query parameters

Parameter	Description
status	Filter by OPEN, INVESTIGATING, RESOLVED, or DISMISSED
severity	Filter by INFO, MEDIUM, HIGH, or CRITICAL
from / to	Date range filter on detectedAt
assignedTo	Filter by assigned user email
limit / cursor	Pagination (default limit: 25, max: 100)

PATCH/shadow-ai/:id

Update the status, assignee, or notes on a detection. To resolve, set status: RESOLVED along with a resolution value.

Mark as investigating

bash

curl -X PATCH https://api.audital.ai/v1/shadow-ai/sad_01HZABCDEF1234567890ABCD \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INVESTIGATING",
    "assignedTo": "compliance@example.com",
    "notes": "Contacted Engineering team lead. Reviewing whether usage needs to be onboarded or stopped."
  }'

json

{
  "id": "sad_01HZABCDEF1234567890ABCD",
  "status": "INVESTIGATING",
  "assignedTo": "compliance@example.com",
  "notes": "Contacted Engineering team lead. Reviewing whether usage needs to be onboarded or stopped.",
  "updatedAt": "2026-03-02T14:00:00.000Z"
}

Resolve by onboarding

bash

curl -X PATCH https://api.audital.ai/v1/shadow-ai/sad_01HZABCDEF1234567890ABCD \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "RESOLVED",
    "resolution": "ONBOARDED",
    "resolvedModelId": "mdl_def456",
    "notes": "Team confirmed. Model registered with Audital as mdl_def456. Usage now governed."
  }'

GET/shadow-ai/stats

Aggregate statistics useful for compliance dashboards and board reporting.

bash

curl https://api.audital.ai/v1/shadow-ai/stats \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxx"

json

{
  "summary": {
    "openDetections": 3,
    "investigatingDetections": 1,
    "resolvedThisMonth": 5,
    "totalExternalAiEndpointsDetected": 7,
    "estimatedMonthlySpendUSD": 142.80,
    "estimatedPiiExposureRisk": "MEDIUM"
  },
  "providers": [
    { "name": "OpenAI", "detections": 4, "callVolume": 8420, "registered": 1 },
    { "name": "Anthropic", "detections": 2, "callVolume": 2100, "registered": 0 },
    { "name": "Cohere", "detections": 1, "callVolume": 340, "registered": 0 }
  ],
  "trend": {
    "detectionsLast30Days": [
      { "date": "2026-02-01", "count": 0 },
      { "date": "2026-02-15", "count": 1 },
      { "date": "2026-03-01", "count": 2 }
    ]
  }
}

Handling Shadow AI webhooks

Audital fires a shadow_ai.detected webhook event whenever a new detection is created. See the Webhooks page for verification instructions.

webhook-handler.js·javascript

// Handle Shadow AI webhook events
// POST https://your-app.example.com/webhooks/audital

app.post('/webhooks/audital', (req, res) => {
  const sig = req.headers['x-audital-signature'];
  const event = req.body;

  if (event.type === 'shadow_ai.detected') {
    const detection = event.data;
    console.log(`Shadow AI detected: ${detection.details.aiProvider}`);
    console.log(`Severity: ${detection.severity}`);
    console.log(`Estimated calls: ${detection.details.estimatedCallVolume}`);

    // Notify compliance team
    await notifyComplianceTeam(detection);

    // Auto-assign if high severity
    if (detection.severity === 'HIGH' || detection.severity === 'CRITICAL') {
      await fetch(`https://api.audital.ai/v1/shadow-ai/${detection.id}`, {
        method: 'PATCH',
        headers: { Authorization: `Bearer ${process.env.AUDITAL_API_KEY}` },
        body: JSON.stringify({ status: 'INVESTIGATING', assignedTo: 'compliance@example.com' }),
      });
    }
  }

  res.json({ received: true });
});

Webhooks →Audit Events API →