VectorGate API Documentation

VectorGate is an edge configuration API for teams that manage routing rules, health checks, and traffic policies across distributed applications.

Authentication

All requests must include an API key in the Authorization header using the Bearer scheme. Keys are generated in the VectorGate workspace console.

GET /v2/rules HTTP/1.1
Host: api.vectorgate.dev
Authorization: Bearer vg_live_sk_v2_Xk9mP3rQ2nL8wT5...
Content-Type: application/json

Key Types

Base URL & Versioning

The current stable version is v2. All endpoint paths are relative to:

https://api.vectorgate.dev/v2

Breaking changes are released under a new version prefix. Deprecated versions remain available for a minimum of 12 months after the successor ships.

Request Format

All request and response bodies are JSON. Set Content-Type: application/json on every write request. Timestamps are Unix seconds (UTC).

Rules

A rule describes how matching requests are evaluated at the edge. Active rules are applied in priority order and can be rolled back by snapshot version.

curl https://api.vectorgate.dev/v2/rules \
  -H "Authorization: Bearer vg_live_sk_v2_Xk9mP3rQ2nL8wT5" \
  -G -d "limit=5" -d "status=active"

{
  "object": "list",
  "data": [
    {
      "id":         "rule_01HX9K3M7PQ6RSTV2W4N8A",
      "object":     "rule",
      "route_id":   "rt_01HW2K1M6PC5RSTU1W3M7A",
      "name":       "EU read traffic",
      "priority":   40,
      "status":     "active",
      "created_at": 1714320000,
      "updated_at": 1714320047
    }
  ],
  "has_more":    true,
  "next_cursor": "cur_eyJpZCI6Im1zZ18wMUhYOUsifQ"
}

Routes

Routes define public hostnames, upstream pools, and policy boundaries for edge traffic. Configure health checks, fallback targets, and TLS settings at the route level.

{
  "object": "list",
  "data": [
    {
      "id":         "rt_01HW2K1M6PC5RSTU1W3M7A",
      "object":     "route",
      "name":       "Public API",
      "hostname":   "api.example.net",
      "mode":       "balanced",
      "enabled":  true,
      "created_at": 1710000000
    },
    {
      "id":         "rt_01HW4N2P8RF7TUVW3X6Q9B",
      "object":     "route",
      "name":       "Asset Gateway",
      "hostname":   "assets.example.net",
      "mode":       "cache_first",
      "enabled":  true,
      "created_at": 1710100000
    }
  ]
}

Webhooks

VectorGate sends a signed POST to your endpoint whenever a tracked configuration or route event occurs. Configure endpoints in the workspace console or via the Webhooks API.

Signature Verification

import hmac, hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    timestamp, received = signature.split(",", 1)
    msg = f"{timestamp}.{payload.decode()}"
    computed = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, received)

Event Types

Webhook Payload

All events share a common envelope with an event-specific data object.

{
  "id":         "evt_01HZ1K4N8PQ8RSUV4Y6O0C",
  "object":     "event",
  "type":       "route.published",
  "created_at": 1714320047,
  "data": {
    "route_id":    "rt_01HW2K1M6PC5RSTU1W3M7A",
    "snapshot_id": "snap_01HZ1K4N8PQ8RSUV4Y6O0C",
    "region":      "global",
    "published_at": 1714320047
  }
}

Error Codes

VectorGate uses standard HTTP status codes. Error responses always include a JSON body with a machine-readable code and a human-readable message.

Error Object

{
  "error": {
    "code":       "route_disabled",
    "message":    "The specified route is currently disabled.",
    "param":      "route_id",
    "request_id": "req_01HZ3P6Q9RF4STUW5Z8R1D"
  }
}

HTTP Status Codes

Application Error Codes

Rate Limits

Limits are enforced per API key using a sliding window. Responses always include current limit state in response headers.

Limits by Plan

SDKs & Libraries

Official client libraries are maintained for the most popular languages. Community libraries are listed in the GitHub org.

Node.js Quick Start

import VectorGate from "@vectorgate/sdk";

const client = new VectorGate({ apiKey: process.env.VECTORGATE_API_KEY! });

const rule = await client.rules.create({
  route_id: "rt_01HW2K1M6PC5RSTU1W3M7A",
  name:     "EU read traffic",
  priority: 40,
  match:    { region: ["eu-central-1"], method: "GET" },
});

console.log(rule.id); // "rule_01HY3K8M9PQ7RSUV3X5N9B"

Python Quick Start

import vectorgate, os

client = vectorgate.Client(api_key=os.environ["VECTORGATE_API_KEY"])

rule = client.rules.create(
    route_id="rt_01HW2K1M6PC5RSTU1W3M7A",
    name="EU read traffic",
    priority=40,
    match={"region": ["eu-central-1"], "method": "GET"},
)

print(rule.id)  # "rule_01HY3K8M9PQ7RSUV3X5N9B"

Changelog

v2.4 - 2026-01-14

• Added snapshot diffing for route publication workflows.
• New webhook event: upstream.recovered for health check recovery.
• Rate-limit headers now use the X-RateLimit-* naming convention.
• Deprecated v1 API; sunset date 2026-09-15.

v2.3 - 2025-08-20

• Weighted upstream support for gradual traffic migration.
• Restricted API keys with per-resource and per-method scopes.
• Improved webhook retry policy with 5 attempts and exponential back-off.

v2.2 - 2025-03-05

• Cache-first route mode.
• Added metadata field to rule objects.
• New route.rollback webhook event.