API Reference

Volledige REST API documentatie voor de ShadowGuard Agent API. Alle endpoints gebruiken JSON request/response bodies.

Base URL:https://shadowguard.nl/api/agent

Security & abuse controls

API keys zijn user- en tenant-gebonden. Bij abuse kun je keys direct revoken in het dashboard, en geblokkeerde accounts verliezen API key-toegang automatisch.

401 ongeldige of verlopen key

403 onvoldoende scope of geblokkeerde user

429 rate limit of anti-abuse limiet geraakt

Authenticatie

POST/api/agent/auth

Valideer een API-sleutel en ontvang sessie-informatie met beschikbare endpoints en permissions.

Request Body

Parameter	Type	Verplicht	Beschrijving
`api_key`	string	verplicht	Je ShadowGuard API key (begint met sg_)

Voorbeelden

curl

curl -X POST https://shadowguard.nl/api/agent/auth \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sg_jouw_api_key"}'

▶JavaScript / TypeScript

const response = await fetch('https://shadowguard.nl/api/agent/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ api_key: 'sg_jouw_api_key' }),
});

const data = await response.json();
console.log(data.agent.permissions);

▶Python

import requests

response = requests.post(
    'https://shadowguard.nl/api/agent/auth',
    json={'api_key': 'sg_jouw_api_key'}
)

data = response.json()
print(data['agent']['permissions'])

Response 200

{
  "authenticated": true,
  "agent": {
    "key_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Mijn CI/CD Agent",
    "permissions": ["read_scans", "write_scans", "read_findings", "suggest_fixes"],
    "rate_limit": 100
  },
  "endpoints": {
    "scans": "/api/agent/scans",
    "scan_trigger": "/api/agent/scan",
    "findings": "/api/agent/findings",
    "suggestions": "/api/agent/suggestions",
    "docs": "/api/agent/docs",
    "config": "/api/agent/config",
    "webhooks": "/api/agent/webhooks"
  }
}

Foutcodes

400api_key ontbreekt of is geen string

401Ongeldige API key of key is inactief

500Interne serverfout

Scans

POST/api/agent/scan

Start een nieuwe beveiligingsscan op een bestaande site. Voert SSL, header en endpoint scans uit en berekent een security score.

Request Body

Parameter	Type	Verplicht	Beschrijving
`site_id`	string (UUID)	verplicht	ID van de site om te scannen
`url`	string	optioneel	Override URL (anders wordt de site URL gebruikt)

Vereiste permission

write_scans

Voorbeeld

curl

curl -X POST https://shadowguard.nl/api/agent/scan \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sg_jouw_api_key" \
  -d '{
    "site_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

▶JavaScript / TypeScript

const response = await fetch('https://shadowguard.nl/api/agent/scan', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sg_jouw_api_key',
  },
  body: JSON.stringify({ site_id: '550e8400-e29b-41d4-a716-446655440000' }),
});

const scan = await response.json();
console.log(`Score: ${scan.score}, Grade: ${scan.grade}`);

▶Python

import requests

response = requests.post(
    'https://shadowguard.nl/api/agent/scan',
    headers={'Authorization': 'Bearer sg_jouw_api_key'},
    json={'site_id': '550e8400-e29b-41d4-a716-446655440000'}
)

scan = response.json()
print(f"Score: {scan['score']}, Grade: {scan['grade']}")

Response 201

{
  "scan_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://mijn-site.nl",
  "score": 82,
  "grade": "goed",
  "counts": {
    "critical": 0,
    "high": 1,
    "medium": 3,
    "low": 2
  },
  "findings_count": 6,
  "scanned_at": "2026-02-07T12:00:00.000Z",
  "detail_url": "/api/agent/scans/d290f1ee-6c54-4b01-90e6-d701748f0851"
}

GET/api/agent/scans

Lijst van recente beveiligingsscans met paginering en filters.

Query Parameters

Parameter	Type	Verplicht	Beschrijving
`limit`	number	optioneel	Aantal resultaten (standaard 20, max 100)
`offset`	number	optioneel	Offset voor paginering (standaard 0)
`site_id`	string (UUID)	optioneel	Filter op specifieke site
`grade`	string	optioneel	Filter op grade: uitstekend, goed, matig, zwak, kritiek
`since`	string (ISO 8601)	optioneel	Scans na deze datum
`until`	string (ISO 8601)	optioneel	Scans voor deze datum

Vereiste permission

read_scans

Voorbeeld

curl

curl "https://shadowguard.nl/api/agent/scans?limit=10&grade=kritiek" \
  -H "Authorization: Bearer sg_jouw_api_key"

Response 200

{
  "scans": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "site_id": "550e8400-e29b-41d4-a716-446655440000",
      "site_name": "Mijn Website",
      "site_url": "https://mijn-site.nl",
      "score": 45,
      "grade": "kritiek",
      "ssl_score": 90,
      "headers_score": 30,
      "endpoints_score": 20,
      "detected_platform": "nextjs",
      "findings_count": 12,
      "critical_count": 2,
      "high_count": 4,
      "medium_count": 3,
      "low_count": 3,
      "scanned_at": "2026-02-07T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Findings

GET/api/agent/findings

Zoek bevindingen (findings) over alle scans heen met geavanceerde filters. Resultaten worden gesorteerd op ernst (critical eerst).

Query Parameters

Parameter	Type	Verplicht	Beschrijving
`limit`	number	optioneel	Aantal resultaten (standaard 50, max 200)
`offset`	number	optioneel	Offset voor paginering (standaard 0)
`severity`	string	optioneel	CRITICAL \| HIGH \| MEDIUM \| LOW
`category`	string	optioneel	SSL_TLS \| SECURITY_HEADER \| EXPOSED_ENDPOINT
`status`	string	optioneel	OPEN \| IN_PROGRESS \| RESOLVED \| ACCEPTED_RISK
`site_id`	string (UUID)	optioneel	Filter op specifieke site
`search`	string	optioneel	Zoek in titel en beschrijving

Vereiste permission

read_findings

Voorbeeld

curl

curl "https://shadowguard.nl/api/agent/findings?severity=CRITICAL&status=OPEN" \
  -H "Authorization: Bearer sg_jouw_api_key"

▶JavaScript / TypeScript

const response = await fetch(
  'https://shadowguard.nl/api/agent/findings?severity=CRITICAL&status=OPEN',
  { headers: { 'Authorization': 'Bearer sg_jouw_api_key' } }
);

const { findings, summary } = await response.json();
console.log(`${summary.critical} kritieke bevindingen`);

▶Python

import requests

response = requests.get(
    'https://shadowguard.nl/api/agent/findings',
    headers={'Authorization': 'Bearer sg_jouw_api_key'},
    params={'severity': 'CRITICAL', 'status': 'OPEN'}
)

data = response.json()
print(f"{data['summary']['critical']} kritieke bevindingen")

Response 200

{
  "findings": [
    {
      "id": "finding-uuid",
      "scan_id": "scan-uuid",
      "site_id": "site-uuid",
      "site_name": "Mijn Website",
      "site_url": "https://mijn-site.nl",
      "finding_type": "missing_hsts",
      "category": "SECURITY_HEADER",
      "severity": "HIGH",
      "status": "OPEN",
      "title": "Strict-Transport-Security header ontbreekt",
      "description": "De HSTS header is niet ingesteld...",
      "impact": "Bezoekers kunnen via HTTP verbinden...",
      "remediation": "Voeg de HSTS header toe aan je server configuratie",
      "endpoint": "https://mijn-site.nl",
      "actual_value": null,
      "expected_value": "max-age=31536000; includeSubDomains",
      "reference_url": "https://developer.mozilla.org/docs/Web/HTTP/Headers/Strict-Transport-Security",
      "created_at": "2026-02-07T12:00:00.000Z"
    }
  ],
  "summary": {
    "critical": 0,
    "high": 3,
    "medium": 5,
    "low": 2
  },
  "pagination": {
    "total": 10,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Suggesties

POST/api/agent/suggestions

Dien een code- of configuratieverbetering in. Suggesties worden beoordeeld door het team.

Request Body

Parameter	Type	Verplicht	Beschrijving
`type`	string	verplicht	code_fix \| config_change \| security_improvement
`title`	string	verplicht	Titel (minimaal 5 tekens)
`description`	string	verplicht	Beschrijving (minimaal 10 tekens)
`diff`	string	optioneel	Unified diff van de voorgestelde wijziging
`file_path`	string	optioneel	Pad naar het doelbestand
`metadata`	object	optioneel	Extra context als JSON object

Vereiste permission

suggest_fixes

Voorbeeld

curl

curl -X POST https://shadowguard.nl/api/agent/suggestions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sg_jouw_api_key" \
  -d '{
    "type": "security_improvement",
    "title": "HSTS header toevoegen",
    "description": "Voeg Strict-Transport-Security header toe aan Next.js middleware voor betere HTTPS afdwinging.",
    "file_path": "middleware.ts",
    "diff": "--- a/middleware.ts\n+++ b/middleware.ts\n@@ -5,6 +5,7 @@\n+  response.headers.set('"'"'Strict-Transport-Security'"'"', '"'"'max-age=31536000; includeSubDomains'"'"');"
  }'

Response 201

{
  "suggestion": {
    "id": "suggestion-uuid",
    "type": "security_improvement",
    "title": "HSTS header toevoegen",
    "status": "pending",
    "created_at": "2026-02-07T12:00:00.000Z"
  },
  "message": "Suggestie ingediend ter beoordeling"
}

GET/api/agent/suggestions

Bekijk eerder ingediende suggesties en hun beoordelingsstatus.

Query Parameters

Parameter	Type	Verplicht	Beschrijving
`status`	string	optioneel	pending \| approved \| rejected \| applied
`limit`	number	optioneel	Aantal resultaten (standaard 20, max 100)
`offset`	number	optioneel	Offset voor paginering (standaard 0)

Response 200

{
  "suggestions": [
    {
      "id": "suggestion-uuid",
      "type": "security_improvement",
      "title": "HSTS header toevoegen",
      "description": "Voeg Strict-Transport-Security header toe...",
      "file_path": "middleware.ts",
      "status": "approved",
      "review_notes": "Goedgekeurd, wordt toegepast in volgende release",
      "reviewed_at": "2026-02-08T10:00:00.000Z",
      "created_at": "2026-02-07T12:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Configuratie

GET/api/agent/config

Lees de ShadowGuard platformconfiguratie. Bevat statistieken, beschikbare plannen, feature flags en scanner-instellingen. Geen gevoelige data.

Vereiste permission

read_config

Voorbeeld

curl

curl https://shadowguard.nl/api/agent/config \
  -H "Authorization: Bearer sg_jouw_api_key"

Response 200

{
  "platform": {
    "name": "ShadowGuard",
    "version": "2.0.0",
    "description": "Security monitoring platform voor Nederlandse MKB"
  },
  "stats": {
    "total_sites": 1250,
    "platforms": {
      "wordpress": 420,
      "nextjs": 380,
      "webflow": 280,
      "lovable": 170
    },
    "total_tenants": 450,
    "active_tenants": 380
  },
  "plans": [
    {
      "id": "plan-uuid",
      "name": "Pro",
      "tier": "pro",
      "monthly_price_eur": 2900,
      "max_sites": 25,
      "max_api_calls_per_month": 10000,
      "max_scans_per_month": 500,
      "features": ["api_access", "sdk_protection", "webhooks"]
    }
  ],
  "feature_flags": [
    {
      "key": "sdk_auto_update",
      "description": "Automatische signature updates",
      "enabled": true,
      "rollout_percentage": 100
    }
  ],
  "scanner": {
    "categories": ["SSL_TLS", "SECURITY_HEADER", "EXPOSED_ENDPOINT"],
    "severity_levels": ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
    "grades": ["uitstekend", "goed", "matig", "zwak", "kritiek"],
    "supported_platforms": ["wordpress", "nextjs", "webflow", "lovable"]
  },
  "api": {
    "version": "v1",
    "rate_limit_default": 100,
    "permissions": [
      "read_scans", "write_scans", "read_findings",
      "suggest_fixes", "read_docs", "read_config", "write_config"
    ]
  }
}

Webhooks

POST/api/agent/webhooks

Registreer een webhook om notificaties te ontvangen bij scan completion, nieuwe findings en meer.

Request Body

Parameter	Type	Verplicht	Beschrijving
`url`	string	verplicht	HTTPS webhook URL
`events`	string[]	verplicht	Event types om te ontvangen
`secret`	string	optioneel	Signing secret (automatisch gegenereerd als niet opgegeven)

Beschikbare events

scan_completedWanneer een scan is afgerond

finding_newWanneer een nieuwe finding wordt ontdekt

finding_resolvedWanneer een finding is opgelost

suggestion_reviewedWanneer een suggestie is beoordeeld

Voorbeeld

curl

curl -X POST https://shadowguard.nl/api/agent/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sg_jouw_api_key" \
  -d '{
    "url": "https://jouw-server.nl/webhooks/shadowguard",
    "events": ["scan_completed", "finding_new"]
  }'

Response 201

{
  "webhook": {
    "id": "webhook-uuid",
    "url": "https://jouw-server.nl/webhooks/shadowguard",
    "events": ["scan_completed", "finding_new"],
    "secret": "whsec_Ab3dEf6gH...",
    "enabled": true,
    "created_at": "2026-02-07T12:00:00.000Z"
  },
  "message": "Webhook geregistreerd. Bewaar het secret veilig - het wordt niet meer getoond."
}

Let op: Het webhook secret wordt alleen getoond bij aanmaak. Sla het veilig op voor het verwerken van webhook payloads.

GET/api/agent/webhooks

Lijst van alle geregistreerde webhooks met hun status en laatste trigger-tijdstip.

Response 200

{
  "webhooks": [
    {
      "id": "webhook-uuid",
      "url": "https://jouw-server.nl/webhooks/shadowguard",
      "events": ["scan_completed", "finding_new"],
      "enabled": true,
      "last_triggered_at": "2026-02-07T11:30:00.000Z",
      "failure_count": 0,
      "created_at": "2026-02-01T10:00:00.000Z"
    }
  ]
}

DELETE/api/agent/webhooks?id={webhook-id}

Verwijder een geregistreerde webhook.

Query Parameters

Parameter	Type	Verplicht	Beschrijving
`id`	string (UUID)	verplicht	ID van de webhook om te verwijderen

Voorbeeld

curl

curl -X DELETE "https://shadowguard.nl/api/agent/webhooks?id=webhook-uuid" \
  -H "Authorization: Bearer sg_jouw_api_key"

Response 200

{ "message": "Webhook verwijderd" }

Foutafhandeling

Alle API endpoints retourneren consistente error responses in JSON formaat.

Error response formaat

{
  "error": "Beschrijving van de fout in het Nederlands"
}

HTTP Status Codes

200Succesvol verzoek

201Resource succesvol aangemaakt

400Ongeldig verzoek (ontbrekende of foute parameters)

401Niet geauthenticeerd (ongeldige of ontbrekende API key)

403Onvoldoende permissions voor deze actie

404Resource niet gevonden

429Rate limit overschreden (wacht en probeer opnieuw)

500Interne serverfout

Custom integratie nodig? GuardFoundry bouwt het voor uMeer info

Volgende stap

Bekijk de SDK documentatie voor runtime beveiliging.

SDK Documentatie