Assets API

Assets API

Create, read, update, and delete target assets via the API.

Endpoints

Method	Endpoint	Description
GET	/assets	List all assets
GET	/assets/{id}	Get asset by ID
GET	/projects/{id}/assets	List project assets
POST	/assets	Create asset
PUT	/assets/{id}	Update asset
DELETE	/assets/{id}	Delete asset

Asset Object

{
  "id": "asset_abc123",
  "project_id": "proj_xyz789",
  "name": "Web Server 01",
  "type": "server",
  "ip_address": "192.168.1.10",
  "hostname": "web01.example.com",
  "ports": [
    {"port": 80, "protocol": "tcp", "service": "http"},
    {"port": 443, "protocol": "tcp", "service": "https"}
  ],
  "os": "Ubuntu 22.04 LTS",
  "status": "tested",
  "notes": "Primary web server",
  "tags": ["production", "web"],
  "findings_count": 3,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-16T14:30:00Z"
}

List Assets

GET /assets

Query Parameters

Parameter	Type	Description
page	integer	Page number
limit	integer	Items per page
project_id	string	Filter by project
type	string	Filter by type
status	string	Filter by status
search	string	Search name/IP/hostname

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/assets?project_id=proj_xyz789&type=server" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "asset_abc123",
      "name": "Web Server 01",
      "ip_address": "192.168.1.10",
      "type": "server",
      "status": "tested"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 45,
    "pages": 1
  }
}

Get Asset

GET /assets/{id}

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/assets/asset_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Asset

POST /assets

Request Body

Field	Type	Required	Description
project_id	string	Yes	Project ID
name	string	Yes	Asset name
type	string	No	Asset type
ip_address	string	No	IP address
hostname	string	No	Hostname
ports	array	No	Port information
os	string	No	Operating system
status	string	No	Testing status
notes	string	No	Notes
tags	array	No	Tags

Example Request

curl -X POST "https://{tenant}.nforged.com/api/v1/assets" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xyz789",
    "name": "Database Server",
    "type": "server",
    "ip_address": "192.168.1.20",
    "hostname": "db01.example.com",
    "ports": [
      {"port": 3306, "protocol": "tcp", "service": "mysql"}
    ],
    "os": "Ubuntu 22.04",
    "status": "not_tested"
  }'

Update Asset

PUT /assets/{id}

Example Request

curl -X PUT "https://{tenant}.nforged.com/api/v1/assets/asset_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "tested",
    "notes": "Testing completed 2024-01-16"
  }'

Delete Asset

DELETE /assets/{id}

Example Request

curl -X DELETE "https://{tenant}.nforged.com/api/v1/assets/asset_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk Import

Import multiple assets:

POST /assets/bulk

{
  "project_id": "proj_xyz789",
  "assets": [
    {"name": "Server 1", "ip_address": "192.168.1.1"},
    {"name": "Server 2", "ip_address": "192.168.1.2"}
  ]
}

Nmap Import

Import assets from Nmap XML:

POST /projects/{id}/import/nmap

curl -X POST "https://{tenant}.nforged.com/api/v1/projects/proj_xyz789/import/nmap" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@scan.xml"

Asset Types

Type	Description
server	Server system
workstation	Desktop/laptop
network_device	Router, switch, firewall
web_application	Web app
mobile_application	Mobile app
api	API endpoint
cloud_resource	Cloud service
iot_device	IoT device
other	Other type

Status Values

Value	Description
not_tested	Not yet tested
in_progress	Currently testing
tested	Testing complete
out_of_scope	Excluded

---

Next: Learn about the Reports API