API Reference

Complete REST API documentation for managing projects, credentials, connectors, and proxies.

Base URL

All API endpoints are prefixed with /api/v1. For example:

http://localhost:8000/api/v1/projects

Authentication

All API endpoints except /api/v1/auth/* and /health require a valid JWT token. Mutation endpoints require at least Editor role; user management requires Admin role.

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400
}

Using the Token

Include the token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  http://localhost:8000/api/v1/projects

Check Auth Status

GET /api/v1/auth/status

Projects

Projects provide multi-tenancy support. Each project has its own credentials, connectors, and proxy pools.

List Projects

GET /api/v1/projects

Create Project

POST /api/v1/projects
Content-Type: application/json

{
  "name": "My Project",
  "description": "Production proxy pool",
  "username": "proxy-user",
  "password": "proxy-password",
  "routing_strategy": "round_robin"
}

Get Project

GET /api/v1/projects/{project_id}

Update Project

PATCH /api/v1/projects/{project_id}
Content-Type: application/json

{
  "name": "Updated Name",
  "routing_strategy": "least_used"
}

Delete Project

DELETE /api/v1/projects/{project_id}

Credentials

Credentials store cloud provider authentication details.

List Credentials

GET /api/v1/projects/{project_id}/credentials

Create Credential

POST /api/v1/projects/{project_id}/credentials
Content-Type: application/json

{
  "name": "AWS Production",
  "type": "aws",
  "config": {
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Credential Types: aws, gcp, azure, static

Get Credential

GET /api/v1/projects/{project_id}/credentials/{credential_id}

Update Credential

PATCH /api/v1/projects/{project_id}/credentials/{credential_id}

Delete Credential

DELETE /api/v1/projects/{project_id}/credentials/{credential_id}

Connectors

Connectors define how proxies are provisioned (cloud instances or static).

List Connectors

GET /api/v1/projects/{project_id}/connectors

Create Connector

POST /api/v1/projects/{project_id}/connectors
Content-Type: application/json

{
  "name": "AWS US-East Proxies",
  "credential_id": "credential-uuid",
  "config": {
    "instance_name": "octoprox-proxy",
    "region": "us-east-1",
    "instance_type": "t3.micro",
    "security_group": "sg-0123456789abcdef0",
    "min_proxies": 1,
    "max_proxies": 10
  },
  "routing_config": {
    "domain_whitelist": ["example.com", "api.example.com"]
  }
}

Domain Filtering (routing_config)

Connectors support optional domain-based filtering to control which target domains their proxies serve. The routing_config field accepts:

  • domain_whitelist — Only route requests for these domains through this connector’s proxies.
  • domain_blacklist — Route all requests except these domains through this connector’s proxies.

Whitelist and blacklist are mutually exclusive — you can set one or the other, but not both.

Domain matching is hierarchical: entering bing.com matches bing.com and all subdomains (www.bing.com, images.bing.com, etc.).

Examples:

Whitelist — only allow specific domains:

{
  "routing_config": {
    "domain_whitelist": ["example.com", "api.example.com"]
  }
}

Blacklist — block specific domains:

{
  "routing_config": {
    "domain_blacklist": ["blocked.com", "ads.tracker.net"]
  }
}

No restrictions (default):

{
  "routing_config": {}
}

Get Connector Options

Get available regions, instance types, and other options for each cloud provider:

GET /api/v1/connector-options

Get Connector

GET /api/v1/projects/{project_id}/connectors/{connector_id}

Update Connector

PATCH /api/v1/projects/{project_id}/connectors/{connector_id}
Content-Type: application/json

{
  "name": "Updated Name",
  "routing_config": {
    "domain_whitelist": ["new-domain.com"]
  }
}

Delete Connector

DELETE /api/v1/projects/{project_id}/connectors/{connector_id}

Proxies

Proxies are the actual proxy servers managed by Octoprox.

List Proxies

GET /api/v1/projects/{project_id}/proxies

Create Proxy (Static)

POST /api/v1/projects/{project_id}/proxies
Content-Type: application/json

{
  "connector_id": "connector-uuid",
  "host": "192.168.1.100",
  "port": 3128,
  "protocol": "http",
  "username": "proxy-user",
  "password": "proxy-pass"
}

Protocols: http, https, socks4, socks5

Upload Proxies (Bulk)

Upload multiple proxies from a CSV file:

POST /api/v1/projects/{project_id}/proxies/upload
Content-Type: multipart/form-data

file: proxies.csv
connector_id: connector-uuid

CSV format (one proxy per line):

http://192.168.1.1:8080
socks5://user:pass@10.0.0.1:1080

Get Proxy

GET /api/v1/projects/{project_id}/proxies/{proxy_id}

Delete Proxy

DELETE /api/v1/projects/{project_id}/proxies/{proxy_id}

Metrics

Get Project Metrics

GET /api/v1/projects/{project_id}/metrics

Response:

{
  "total_proxies": 10,
  "healthy_proxies": 8,
  "total_requests": 15420,
  "success_rate": 0.98,
  "avg_latency_ms": 145.2
}

Prometheus Metrics

Export metrics in Prometheus format:

GET /api/v1/projects/{project_id}/metrics/prometheus

Health Check

Public endpoint for load balancer health checks:

GET /health

Response:

{
  "status": "healthy"
}