Datashielder API
Use organization-scoped API keys to read scan credits, list targets, inspect target sets, and request manual scans from your own tooling.
01 / Quick Start
All customer API routes are served from the Datashielder app domain. Send and receive JSON, and authenticate every request with an organization-scoped API key.
curl -H "Authorization: Bearer $DATASHIELDER_API_KEY" \
https://app.datashielder.com/api/external/targets02 / Authentication
API keys are created in Clerk and must be scoped to an organization. Keys with explicit scopes can call only matching routes. Keys created with an empty scope list are treated as full-access organization keys.
| Scope | Access |
|---|---|
| read:org | Read organization summary, counts, and recent scans. |
| read:credits | Read scan credit balance and credit history. |
| read:targets | Read target sets, targets, active state, and latest scan data. |
| write:targets | Create target sets and their targets for the organization. |
| read:reports | Read approved reports and report details for the organization. |
| read:scan_requests | Read manual scan request history. |
| write:scan_requests | Create manual scan requests for targets in the organization. |
03 / Endpoints
Organization metadata, target counts, open report count, and the 10 most recent scans.
Available credits, total purchased, consumed count, and recent credit history.
All target sets, target counts, domains to watch, latest scan timestamp, and target summaries.
Create a target set with a name, optional domains to watch, and optional target hostnames. Targets are validated for blocked and internal hosts before they are saved.
All organization targets, including active state, mode, source, counts, latest scan, and pending scan request.
Approved reports for the organization, with status, scan, target, search, limit, and offset filters.
Full approved report details, including content, URLs, reproduction steps, mitigation steps, scan, target, and domain metadata.
Recent manual scan requests, optionally filtered by pending or fulfilled status.
Create a manual scan request for a target. Consumes a scan credit unless the organization has an active or trialing subscription.
04 / Examples
Use this before offering a manual scan button inside your own portal.
curl -H "Authorization: Bearer $DATASHIELDER_API_KEY" \
"https://app.datashielder.com/api/external/credits?limit=10"Use target IDs from this response when creating manual scan requests.
curl -H "Authorization: Bearer $DATASHIELDER_API_KEY" \
"https://app.datashielder.com/api/external/targets?active=true"Status 0 means pending action. Use limit and offset to paginate through larger report sets.
curl -H "Authorization: Bearer $DATASHIELDER_API_KEY" \
"https://app.datashielder.com/api/external/reports?status=0&limit=100&offset=0"Pass full hostnames in targets. Their domains are reused or created automatically. A successful request returns 201.
curl -X POST \
-H "Authorization: Bearer $DATASHIELDER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"My set","domainsToWatch":["example.com"],"targets":["api.example.com"]}' \
https://app.datashielder.com/api/external/target-setsA successful request returns 201. If a pending request already exists, the API returns 409.
curl -X POST \
-H "Authorization: Bearer $DATASHIELDER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"targetId":123}' \
https://app.datashielder.com/api/external/scan-requests05 / Errors
Failed requests return JSON with an `error` field. Validation failures can also include a `details` object.
{
"error": "Missing required scope: write:scan_requests"
}