API Integration

NEURO provides a comprehensive REST API for building custom integrations, automating workflows, and connecting with third-party tools.

Overview

The API enables:

Programmatic data access
Automated finding creation
Custom tool integration
CI/CD pipeline integration
Reporting automation

API Access

Base URL

https://{tenant}.nforged.com/api/v1

Or for your tenant:

https://{tenant}.nforged.com/api

Authentication

All API requests require authentication via Bearer token:

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

Getting an API Token

Log into NEURO
Go to Settings → API Access
Click Generate API Token
Copy and securely store the token

Quick Start

List Projects

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

Response:

{
  "success": true,
  "data": [
    {
      "id": "proj_123",
      "name": "Q1 Pentest",
      "client_id": "client_456",
      "status": "in_progress"
    }
  ]
}

Create a Finding

curl -X POST "https://{tenant}.nforged.com/api/v1/findings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "title": "SQL Injection in Login",
    "severity": "High",
    "description": "SQL injection vulnerability found...",
    "remediation": "Use parameterized queries..."
  }'

Core Endpoints

Projects

Method	Endpoint	Description
GET	`/projects`	List all projects
GET	`/projects/{id}`	Get project details
POST	`/projects`	Create project
PUT	`/projects/{id}`	Update project
DELETE	`/projects/{id}`	Delete project

Findings

Method	Endpoint	Description
GET	`/findings`	List all findings
GET	`/projects/{id}/findings`	List project findings
GET	`/findings/{id}`	Get finding details
POST	`/findings`	Create finding
PUT	`/findings/{id}`	Update finding
DELETE	`/findings/{id}`	Delete finding

Assets

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

Clients

Method	Endpoint	Description
GET	`/clients`	List all clients
GET	`/clients/{id}`	Get client details
POST	`/clients`	Create client
PUT	`/clients/{id}`	Update client

Request Format

Headers

Required headers:

Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

Request Body

JSON format for POST/PUT:

{
  "field_name": "value",
  "nested": {
    "field": "value"
  }
}

Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "total": 100
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid field value",
    "details": [...]
  }
}

Pagination

List endpoints support pagination:

GET /findings?page=1&limit=50

Parameters:

page: Page number (default: 1)
limit: Items per page (default: 50, max: 100)

Response includes:

{
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 234,
    "pages": 5
  }
}

Filtering

Query Parameters

Filter results using query params:

GET /findings?severity=High&status=Open

Common filters:

severity: Critical, High, Medium, Low, Info
status: Open, Confirmed, Remediated, etc.
project_id: Filter by project
created_after: Date filter
search: Text search

Rate Limiting

API rate limits:

1,000 requests per minute
10,000 requests per hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

When exceeded:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests"
  }
}

Integration Examples

Python Example

import requests

API_URL = "https://{tenant}.nforged.com/api/v1"
TOKEN = "your_api_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# List projects
response = requests.get(f"{API_URL}/projects", headers=headers)
projects = response.json()["data"]

# Create finding
finding = {
    "project_id": "proj_123",
    "title": "XSS in Search",
    "severity": "Medium",
    "description": "Reflected XSS found in search parameter"
}
response = requests.post(f"{API_URL}/findings",
                         json=finding,
                         headers=headers)

JavaScript Example

const API_URL = 'https://{tenant}.nforged.com/api/v1';
const TOKEN = 'your_api_token';

const headers = {
  'Authorization': `Bearer ${TOKEN}`,
  'Content-Type': 'application/json'
};

// List projects
const response = await fetch(`${API_URL}/projects`, { headers });
const { data: projects } = await response.json();

// Create finding
const finding = {
  project_id: 'proj_123',
  title: 'IDOR Vulnerability',
  severity: 'High'
};
await fetch(`${API_URL}/findings`, {
  method: 'POST',
  headers,
  body: JSON.stringify(finding)
});

CI/CD Integration

# GitHub Actions example
- name: Create Finding in NEURO
  run: |
    curl -X POST "${{ secrets.NFORGED_API }}/findings" \
      -H "Authorization: Bearer ${{ secrets.NFORGED_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{"project_id": "proj_123", "title": "${{ env.FINDING_TITLE }}"}'

Webhooks

Configuring Webhooks

Go to Settings → Webhooks
Click Add Webhook
Enter endpoint URL
Select events to receive
Save webhook

Webhook Events

Event	Triggered When
`finding.created`	New finding added
`finding.updated`	Finding modified
`finding.deleted`	Finding removed
`project.created`	New project
`report.generated`	Report created

Webhook Payload

{
  "event": "finding.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "find_789",
    "title": "SQL Injection",
    "project_id": "proj_123"
  }
}

Error Handling

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Error Codes

Code	Description
`INVALID_TOKEN`	Authentication failed
`VALIDATION_ERROR`	Invalid input
`NOT_FOUND`	Resource doesn’t exist
`PERMISSION_DENIED`	Access not allowed

Next: Explore Collaboration Features