REST API Overview

NectoProxy provides a comprehensive REST API that exposes all proxy features programmatically. The API is served on the same port as the Web UI, making it easy to integrate with scripts, CI/CD pipelines, and external tooling.

Base URL

All API endpoints are served under the /api prefix on the Web UI port:

http://localhost:8889/api

Customizable Port

The default UI port is 8889. If you have configured a different port via the uiPort setting, adjust the base URL accordingly.

Request Format

• All request bodies must be sent as JSON with the Content-Type: application/json header.
• Query parameters are used for filtering, pagination, and search operations.
• URL path parameters are used for resource identifiers (e.g., /api/traffic/:id).

# Example: Creating a session with a JSON body
curl -X POST http://localhost:8889/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "My Session"}'

Exception: File Uploads

The HAR import and validate endpoints accept multipart/form-data instead of JSON. See the HAR API documentation for details.

Response Format

All successful responses return JSON. List endpoints typically wrap results in an object with a descriptive key:

{
  "sessions": [
    { "id": "abc123", "name": "My Session", "..." : "..." }
  ]
}

Single-resource responses return the resource directly or within a wrapper:

{
  "id": "abc123",
  "name": "My Session",
  "isActive": true,
  "isRecording": true,
  "createdAt": 1709136000000,
  "updatedAt": 1709136000000,
  "trafficCount": 42,
  "totalBytes": 102400
}

Authentication

No Authentication Required

NectoProxy does not require authentication for API access. The proxy is designed as a local development tool. If you expose it on a network, ensure appropriate firewall rules are in place.

Error Response Format

All errors follow a consistent format with an error field containing a human-readable message:

{
  "error": "Traffic entry not found"
}

Validation errors also use this format:

{
  "error": "Method and URL are required"
}

HTTP Status Codes

Status Code	Meaning	Used When
200 OK	Success	GET, PUT, PATCH, DELETE operations succeed
201 Created	Resource created	POST operations that create new resources
400 Bad Request	Invalid input	Missing required fields, invalid data format
404 Not Found	Resource not found	Requested ID does not exist
500 Internal Server Error	Server error	Unexpected errors during processing

Content-Type Headers

Direction	Header	Value
Request	Content-Type	application/json
Response	Content-Type	application/json
File download	Content-Type	application/json or application/x-pem-file
File upload	Content-Type	multipart/form-data

Common Response Patterns

Success with Data

{
  "entries": [...],
  "count": 42
}

Success without Data

{
  "success": true
}

Deletion Response

{
  "success": true
}

Real-Time Events

In addition to the REST API, NectoProxy provides real-time event streaming via Socket.IO. The Socket.IO server runs on the same host and port as the REST API.

import { io } from 'socket.io-client';

const socket = io('http://localhost:8889');

socket.on('traffic:batch', (entries) => {
  console.log('New traffic:', entries);
});

See the Real-Time Events documentation for a full list of events.

API Sections

Section	Description
Traffic	Inspect, search, delete, and replay HTTP traffic
Sessions	Manage capture sessions
Rules	Create and manage request/response modification rules
Breakpoints	Set breakpoints to intercept and modify live traffic
Network Conditioning	Simulate network conditions (3G, latency, packet loss)
SSL Passthrough	Bypass SSL interception for specific domains
DNS Mapping	Override DNS resolution for custom domain routing
HAR	Import and export traffic in HAR format
Settings	Configure proxy and UI settings
Upstream Proxy	Chain through an upstream proxy server
Certificates	Manage the CA certificate for HTTPS interception
WebSocket Frames	Inspect captured WebSocket frames
Annotations	Add notes and tags to traffic entries
Real-Time Events	Subscribe to live events via Socket.IO

Quick Start Example

# 1. Create a session
curl -X POST http://localhost:8889/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "API Test"}'

# 2. List captured traffic (after browsing through the proxy)
curl http://localhost:8889/api/traffic?limit=10

# 3. Search for specific requests
curl "http://localhost:8889/api/traffic/search?q=api.github.com"

# 4. Export traffic as HAR
curl http://localhost:8889/api/har/export/SESSION_ID -o traffic.har