Docs / Surface / api

API Reference

All endpoints require a Bearer token: Authorization: Bearer <api-key>.

You can provide your own correlation ID by sending the X-Request-ID header, and Surface echoes it in the response and webhook payload. If omitted, one is generated automatically.

---

POST /api/scan#

Scan a file upload.

Request: multipart/form-data

Query params

Response: see Understanding Results below.

---

POST /api/scan/payload#

Scan a raw text or binary payload for threats.

Request

{
  "payload": "string",
  "label": "optional name, e.g. agent-message.json",
  "encoding": "raw"
}

Response: same shape as file scan. See Understanding Results.

---

Async / Deferred Scanning#

For large files or high-throughput workflows, add ?defer=true to the scan request. Explicit ?defer=true requires a Standard or Pro plan; on Free and Starter it returns an error. Files larger than 25 MB are deferred automatically on every plan even without the flag.

curl -X POST "https://app.tendrl.com/surface/api/scan?defer=true" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@large_archive.zip"

Returns immediately with HTTP 202 Accepted:

{
  "scanId": "uuid",
  "requestId": "uuid",
  "status": "pending",
  "message": "Scan queued. Poll GET /api/scan/{scanId} for results."
}

• Use scanId to poll for results via GET /api/scan/{scanId}
• Use requestId to correlate with webhooks (same ID in both the response and webhook payload)

If you've configured a webhook, results are also POSTed to your endpoint when the scan finishes.

---

Understanding Results#

Every scan returns a JSON response with a safety score and threat details:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "report.pdf",
  "hash": "e3b0c44298fc1c149afbf4c8...",
  "size": 245760,
  "contentType": "application/pdf",
  "safetyScore": {
    "score": 95,
    "threatLevel": "Clean",
    "confidence": "High",
    "confidenceScore": 0.85,
    "confidenceReason": "3 engines analyzed; signature check clear; no rule matches",
    "primaryThreat": "No threats detected",
    "threatSummary": "No threats detected",
    "enginesUsed": ["Malware Signatures", "YARA", "Static Analysis"],
    "recommendedAction": "Allow",
    "coverage": "full"
  },
  "scanTimeMs": 1250,
  "scanType": "file",
  "timestamp": 1741500000
}

Key fields#

Safety score ranges#

Scores combine signals from all engines. A file flagged by multiple independent engines scores lower than one flagged by a single check.

Payload scan additional fields#

Payload scans include additional engine results for agentic/content security:

Payloads are not retained. The match, excerpt, evidence and redacted fields are the only pieces of a payload that persist in scan history, and each is capped at roughly 200 characters — enough to confirm or dispute a verdict, not to reconstruct the content.

Fractional numbers in every scan response (confidenceScore, entropy values, engine confidences) are rounded to two decimal places.

---

GET /api/scan/{scanId}#

Retrieve a deferred scan result by scan ID.

While the scan is in progress, returns a pending envelope:

{
  "scanId": "uuid",
  "requestId": "uuid",
  "status": "pending",
  "filename": "large_archive.zip",
  "createdAt": "2025-03-09T12:00:00Z"
}

When complete, the response is a top-level envelope with summary fields, and the full synchronous-style scan result nested under result:

{
  "scanId": "uuid",
  "requestId": "uuid",
  "status": "complete",
  "filename": "large_archive.zip",
  "fileHash": "e3b0c44298fc1c149afbf4c8...",
  "fileSize": 245760,
  "contentType": "application/zip",
  "safetyScore": 95,
  "threatLevel": "Clean",
  "primaryThreat": "No threats detected",
  "scanTimeMs": 1250,
  "creditsUsed": 1,
  "createdAt": "2025-03-09T12:00:00Z",
  "result": {
    "...": "full scan result, same shape as a synchronous scan (see Understanding Results)"
  }
}

---

GET /api/account/history/{scan_id}#

Retrieve a previous scan result by ID.

---

GET /api/account/history#

Paginated scan history.

Query params

---

GET /api/account/usage#

Current month usage for the authenticated account.

{
  "scans_used": 43,
  "max_scans": 100,
  "scans_remaining": 57,
  "max_file_size_mb": 10,
  "plan_tier": "free",
  "reset_at": "2025-04-01T00:00:00Z",
  "daily_volume": { "dates": ["2025-03-08", "2025-03-09"], "counts": [12, 31] }
}

max_scans and max_file_size_mb come from your plan tier (Free starts at 100 scans/month and 10 MB; higher tiers raise both).

---

Rate Limits#

When a per-minute limit is reached the API returns 429 Too Many Requests. Monthly scan quotas depend on your plan; when exhausted, scan requests return 402. See tendrl.com/pricing for details.

---

Error codes#

Errors return an error message and a requestId. Most also carry fileType, profile, feature, current_plan or code fields relevant to that error — branch on the HTTP status first, and check code for the two cases below where the same status covers more than one reason.

← Back to Surface docs