API Reference - NetfillX

Getting Started

The NetfillX API lets you programmatically route fill requests across our global edge network of 190 nodes. All API access is over HTTPS and returns JSON-encoded responses.

Base URL

BASE URL
https://api.netfillx.com/v1

Quick Start

Make your first fill-request route in under 60 seconds. Replace nfx_live_xxxxx with your actual API key from the dashboard.

CURL

curl -X POST https://api.netfillx.com/v1/route \
  -H "Authorization: Bearer nfx_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "fill_request": {
      "type": "network_route",
      "source": "us-east-1",
      "destination": "auto",
      "priority": "low_latency",
      "payload_size": 1024,
      "ttl": 300
    }
  }'

New to NetfillX? Visit your dashboard to generate an API key before making requests. Keys are prefixed with nfx_live_ for production and nfx_test_ for sandbox environments.

Authentication

NetfillX uses API keys to authenticate requests. Include your key in the Authorization header using the Bearer scheme on every request. Requests without a valid key return 401 unauthorized.

Header	Value	Required
Authorization	`Bearer nfx_live_<key>`	Yes
Content-Type	`application/json`	Yes (write ops)
X-Request-ID	Any UUID string	Optional
X-NFX-Region	`us-east-1` etc.	Optional

Key Scopes

Scope	Prefix	Description
Live	`nfx_live_`	Full production access. Requests count against your quota.
Test	`nfx_test_`	Sandbox mode. Responses are simulated, never billed.
Restricted	`nfx_rk_`	Read-only analytics access. Cannot create or delete routes.

Keep keys secret. Never expose API keys in client-side JavaScript or public repositories. Rotate compromised keys immediately from the dashboard.

EXAMPLE AUTH HEADER

Authorization: Bearer nfx_live_sk_9fX2mKpLqR8vT3wZ

Fill Requests

Create a Fill Route

POST /v1/route

Submits a fill request to the routing engine. NetfillX selects the optimal edge path based on your priority preference, current network conditions, and real-time node health scores across all 190 edge nodes.

Request Body Parameters

Parameter	Type	Required	Description
fill_request.type	`string`	Yes	`network_route` \| `bgp_fill` \| `mpls_fill`
fill_request.source	`string`	Yes	Origin region identifier, e.g. `us-east-1`
fill_request.destination	`string`	No	`auto` (default) or a specific region code
fill_request.priority	`string`	No	`low_latency` \| `high_throughput` \| `balanced`
fill_request.payload_size	`integer`	No	Expected payload in bytes. Used for buffer pre-allocation.
fill_request.ttl	`integer`	No	Route TTL in seconds. Default: `300`. Max: `86400`.
fill_request.metadata	`object`	No	Arbitrary key-value pairs attached to the route record.

REQUEST BODY

POST /v1/route
Authorization: Bearer nfx_live_sk_9fX2mKpLqR8vT3wZ
Content-Type: application/json

{
  "fill_request": {
    "type":         "network_route",  // network_route | bgp_fill | mpls_fill
    "source":       "us-east-1",      // source region
    "destination":  "auto",           // auto | specific region
    "priority":     "low_latency",    // low_latency | high_throughput | balanced
    "payload_size": 1024,             // bytes
    "ttl":          300               // seconds
  }
}

RESPONSE 200 OK

{
  "id":      "req_2xK9mLpQrT4vW",
  "status":  "routed",
  "route": {
    "path":              ["us-east-1", "eu-central-1", "ap-southeast-1"],
    "selected_endpoint": "https://edge-07.netfillx.com",
    "latency_ms":        0.8,
    "fill_rate":         0.99
  },
  "created_at": "2025-11-12T14:23:01Z"
}

List Active Routes

GET /v1/routes

Returns a paginated list of all routes under your account, ordered by creation time descending.

Query Param	Type	Description
limit	`integer`	Results per page. Default: `20`. Max: `100`.
cursor	`string`	Pagination cursor from a previous response's `next_cursor`.
status	`string`	Filter by `active` \| `expired` \| `failed`.
region	`string`	Filter by source region, e.g. `eu-central-1`.

RESPONSE 200 OK

{
  "data": [
    {
      "id":         "req_2xK9mLpQrT4vW",
      "status":     "active",
      "source":     "us-east-1",
      "endpoint":   "https://edge-07.netfillx.com",
      "fill_rate":  0.99,
      "expires_at": "2025-11-12T14:28:01Z"
    }
  ],
  "next_cursor": "cur_mQ8vRp3xL1",
  "has_more":    true
}

Delete a Route

DELETE /v1/routes/{id}

Immediately removes an active route and releases its reserved edge capacity. In-flight packets are drained before teardown (up to 500ms grace period).

RESPONSE 200 OK
{
  "id":      "req_2xK9mLpQrT4vW",
  "deleted": true
}

Analytics

Get Fill Rate Metrics

GET /v1/analytics/fill-rate

Returns aggregated fill-rate and latency metrics for your account across the requested time window.

Query Param	Type	Description
window	`string`	`1h` \| `24h` \| `7d` \| `30d`. Default: `24h`.
region	`string`	Scope to a single region. Omit for all regions.
granularity	`string`	`minute` \| `hour` \| `day`. Auto-selected by default.

RESPONSE 200 OK

{
  "window":  "24h",
  "summary": {
    "avg_fill_rate":  0.9987,
    "avg_latency_ms": 0.72,
    "total_requests": 4820103,
    "failed_routes":  6102
  },
  "series": [
    { "ts": "2025-11-12T00:00:00Z", "fill_rate": 0.9991, "latency_ms": 0.68 },
    { "ts": "2025-11-12T01:00:00Z", "fill_rate": 0.9988, "latency_ms": 0.71 }
  ]
}

Webhooks

NetfillX pushes real-time event notifications to your HTTPS endpoint. Register webhook URLs from the dashboard or via POST /v1/webhooks.

Event Types

Event	Trigger
route.created	A new fill route was successfully established.
route.expired	A route's TTL elapsed and was automatically removed.
route.failed	Routing failed after exhausting all fallback paths.
fill_rate.degraded	Account fill rate dropped below 99.5% over a 5-minute window.
endpoint.unhealthy	An edge node you are pinned to failed its health check.

WEBHOOK PAYLOAD
{
  "event":   "route.created",
  "created": 1731418981,
  "data": { "id": "req_2xK9mLpQrT4vW", "fill_rate": 0.99 }
}

Verify authenticity using the X-NFX-Signature-256 header: an HMAC-SHA256 of the raw body signed with your webhook secret.

Errors

NetfillX uses standard HTTP status codes. Error bodies include a machine-readable code and a human-readable message.

HTTP Code	Error Code	Meaning
400	`bad_request`	The request body is malformed or missing required fields.
401	`unauthorized`	API key is missing, invalid, or revoked.
403	`forbidden`	The key exists but lacks permission for this action.
404	`not_found`	The requested resource does not exist.
409	`conflict`	A route with a duplicate idempotency key already exists.
422	`unprocessable`	Validation passed but the route could not be computed.
429	`rate_limited`	You have exceeded your plan's per-second request limit.
500	`server_error`	Unexpected server error. Retryable with exponential backoff.

ERROR BODY
{
  "error": {
    "code":       "rate_limited",
    "message":    "Request rate exceeds plan limit of 100 req/s",
    "retry_after": 1,
    "request_id": "req_err_7Hm3pQ"
  }
}

Rate Limits

Rate limits are applied per API key. Exceeding the per-second burst limit returns 429 rate_limited. The response includes Retry-After and X-RateLimit-Reset headers.

Free

1M req/mo

100 req/s burst

Analytics: 7-day window

Pro

50M req/mo

1,000 req/s burst

Analytics: 90-day window

Enterprise

∞ unlimited

Custom rate limits

Dedicated edge nodes

SDKs

Official client libraries wrap the REST API with idiomatic interfaces, automatic retry with exponential backoff, and full type definitions.

Python Node.js Go Ruby Java PHP

PYTHON

# Install
pip install netfillx

# Usage
from netfillx import NetfillX

client = NetfillX(api_key="nfx_live_sk_9fX2mKpLqR8vT3wZ")

route = client.routes.create(
    type="network_route",
    source="us-east-1",
    priority="low_latency",
    ttl=300
)
print(route.id, route.route.latency_ms)

NODE.JS

// Install
npm install @netfillx/sdk

// Usage
import { NetfillX } from '@netfillx/sdk';

const client = new NetfillX({ apiKey: 'nfx_live_sk_9fX2mKpLqR8vT3wZ' });

const route = await client.routes.create({
  type:     'network_route',
  source:   'us-east-1',
  priority: 'low_latency',
  ttl:      300
});
console.log(route.id, route.route.latency_ms);

GO

// Install
go get github.com/netfillx/go-sdk

// Usage
import nfx "github.com/netfillx/go-sdk"

client := nfx.NewClient("nfx_live_sk_9fX2mKpLqR8vT3wZ")
route, err := client.Routes.Create(nfx.RouteParams{
    Type:     "network_route",
    Source:   "us-east-1",
    Priority: "low_latency",
    TTL:      300,
})