Assets

The Assets API lets you manage your organization's digital assets --- domains, IP addresses, URLs, and network ranges --- that S4E monitors and scans.

List Assets

GET /api/assets

Query Parameters

Parameter Type Default Description
type string all Filter by asset type: domain, ip, url, network.
tag string Filter by tag name.
status string all Filter by status: active, inactive, pending_verification.
search string Full-text search across asset name and metadata.
page integer 1 Page number.
per_page integer 20 Results per page (max 100).
sort_by string created_at Sort field: name, type, created_at, risk_score.
sort_order string desc Sort direction: asc, desc.

Example

curl -X GET "https://api.s4e.io/api/assets?type=domain&status=active&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "a-1001",
      "name": "example.com",
      "type": "domain",
      "status": "active",
      "verified": true,
      "risk_score": 72,
      "tags": ["production", "web"],
      "last_scan": "2026-04-20T08:00:00Z",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

Get Asset Details

GET /api/assets/{id}

Returns full asset information including scan history, finding summary, and metadata.

curl -X GET "https://api.s4e.io/api/assets/a-1001" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "a-1001",
    "name": "example.com",
    "type": "domain",
    "status": "active",
    "verified": true,
    "risk_score": 72,
    "tags": ["production", "web"],
    "metadata": {
      "registrar": "Cloudflare",
      "ip_addresses": ["93.184.216.34"],
      "technologies": ["nginx", "React"]
    },
    "finding_summary": {
      "critical": 1,
      "high": 3,
      "medium": 12,
      "low": 8,
      "info": 22
    },
    "last_scan": "2026-04-20T08:00:00Z",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-04-20T08:30:00Z"
  }
}

Create Asset

POST /api/assets

Request Body

Field Type Required Description
name string Yes Asset identifier (domain, IP, URL).
type string Yes Asset type: domain, ip, url, network.
tags array No Tags for categorization.
metadata object No Additional metadata key-value pairs.

Example

curl -X POST "https://api.s4e.io/api/assets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api.example.com",
    "type": "domain",
    "tags": ["production", "api"],
    "metadata": {
      "team": "backend",
      "environment": "production"
    }
  }'

Response (201 Created)

{
  "data": {
    "id": "a-1002",
    "name": "api.example.com",
    "type": "domain",
    "status": "pending_verification",
    "verified": false,
    "tags": ["production", "api"],
    "created_at": "2026-04-28T12:00:00Z"
  }
}

Update Asset

PUT /api/assets/{id}

curl -X PUT "https://api.s4e.io/api/assets/a-1002" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["production", "api", "critical"],
    "metadata": {
      "team": "platform",
      "environment": "production"
    }
  }'

Delete Asset

DELETE /api/assets/{id}

curl -X DELETE "https://api.s4e.io/api/assets/a-1002" \
  -H "Authorization: Bearer YOUR_API_KEY"

Warning

Deleting an asset removes all associated scan history and findings. This action cannot be undone.

Bulk Import

POST /api/assets/bulk

Import multiple assets at once from a JSON array or CSV.

JSON Import

curl -X POST "https://api.s4e.io/api/assets/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      {"name": "app1.example.com", "type": "domain", "tags": ["production"]},
      {"name": "app2.example.com", "type": "domain", "tags": ["staging"]},
      {"name": "192.168.1.0/24", "type": "network", "tags": ["internal"]}
    ]
  }'

CSV Import

curl -X POST "https://api.s4e.io/api/assets/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @assets.csv

CSV format:

name,type,tags
app1.example.com,domain,"production,web"
app2.example.com,domain,"staging"
10.0.1.0/24,network,"internal"

Bulk Response

{
  "data": {
    "imported": 3,
    "failed": 0,
    "errors": []
  }
}

Verify Asset

POST /api/assets/{id}/verify

Triggers ownership verification for the asset (DNS TXT record, HTML meta tag, or file upload).

curl -X POST "https://api.s4e.io/api/assets/a-1002/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "verification_method": "dns_txt",
    "verification_token": "s4e-verify=abc123def456",
    "instructions": "Add a TXT record with the value above to your domain's DNS."
  }
}

Field Reference

Field Type Description
id string Unique asset identifier.
name string Asset name (domain, IP, URL).
type string Asset type.
status string Current status.
verified boolean Whether ownership is verified.
risk_score integer Calculated risk score (0-100).
tags array User-defined tags.
metadata object Additional key-value metadata.
finding_summary object Finding counts by severity.
last_scan string ISO 8601 timestamp of last scan.
created_at string ISO 8601 creation timestamp.
updated_at string ISO 8601 last update timestamp.

Next Steps