Skip to main content
The GraphQL API is mounted at /graphql on the admin server. It provides full CRUD for every runtime entity — targets, IP pools, and providers — and propagates changes live without a restart. Access the interactive playground at GET http://localhost:8081/graphql.

​
Cascade behaviour

Changes to a provider’s IP list cascade automatically: 
addIpToProvider / removeIpFromProvider
  └─► provider's ip_list updated in repository
       └─► all pools that reference this provider recomputed
            └─► all targets that reference those pools get new resolved_ips
                 └─► target:update events emitted → live pool queues updated
This means you can add or remove an IP from a provider and every target that uses that provider’s IPs through a pool will see the change immediately.

​
Queries

​
targets

List all targets stored in the repository. 
{
  targets {
    name
    regex
    poolName
    mutable
    minRequestInterval
    maxQueueWait
    numRetries
    ipFailuresUntilQuarantine
    quarantineTime
  }
}

​
target(name: String!)

Fetch a single target by name. 
{
  target(name: "google-apis") {
    name
    regex
    poolName
  }
}

​
pools

List all IP pools. 
{
  pools {
    name
    mutable
    ipRequests {
      provider
      count
    }
  }
}

​
pool(name: String!)

Fetch a single pool by name. 
{
  pool(name: "us-pool") {
    name
    ipRequests {
      provider
      count
    }
  }
}

​
providers

List all proxy providers. 
{
  providers {
    name
    ipList
    regionTag
    mutable
  }
}

​
provider(name: String!)

Fetch a single provider by name. 
{
  provider(name: "provider-us") {
    name
    ipList
    regionTag
  }
}

​
status

Current auth state and caller identity. 
{
  status {
    authEnabled
    userSub
    userRole
  }
}

​
Mutations

All mutations require the write permission.

​
Target mutations

​
addTarget

Add a new target. The pool referenced by poolName must already exist in the repository. 
mutation {
  addTarget(input: {
    name: "new-api"
    regex: "api\\.example\\.com"
    poolName: "us-pool"
    minRequestInterval: 2.0
    maxQueueWait: 30.0
    numRetries: 3
    ipFailuresUntilQuarantine: 5
    quarantineTime: 120.0
  }) {
    name
    poolName
  }
}

​
updateTarget

Update an existing mutable target. Replaces the full target definition. 
mutation {
  updateTarget(input: {
    name: "new-api"
    regex: "api\\.example\\.com"
    poolName: "eu-pool"
    minRequestInterval: 5.0
    maxQueueWait: 60.0
    numRetries: 2
    ipFailuresUntilQuarantine: 3
    quarantineTime: 300.0
  }) {
    name
    poolName
  }
}

​
removeTarget

Remove a target from the repository. 
mutation {
  removeTarget(name: "new-api")
}

​
Pool mutations

​
addPool

Add a new IP pool. 
mutation {
  addPool(input: {
    name: "eu-pool"
    ipRequests: [
      { provider: "provider-eu", count: 5 }
    ]
  }) {
    name
    ipRequests {
      provider
      count
    }
  }
}

​
updatePool

Update an existing mutable pool. Triggers a cascade to all targets referencing this pool. 
mutation {
  updatePool(input: {
    name: "eu-pool"
    ipRequests: [
      { provider: "provider-eu", count: 10 }
    ]
  }) {
    name
  }
}

​
removePool

Remove a pool from the repository. 
mutation {
  removePool(name: "eu-pool")
}

​
Provider mutations

​
addProvider

Add a new proxy provider. 
mutation {
  addProvider(input: {
    name: "provider-eu"
    ipList: ["10.2.0.1:3128", "10.2.0.2:3128"]
    regionTag: "EU-West"
    auth: { username: "user", password: "secret" }
  }) {
    name
    ipList
    regionTag
  }
}

​
updateProvider

Update an existing mutable provider. Does not automatically cascade to pools and targets — use addIpToProvider / removeIpFromProvider for live IP changes. 
mutation {
  updateProvider(input: {
    name: "provider-eu"
    ipList: ["10.2.0.1:3128", "10.2.0.2:3128", "10.2.0.3:3128"]
    regionTag: "EU-West"
  }) {
    name
    ipList
  }
}

​
removeProvider

Remove a provider from the repository. 
mutation {
  removeProvider(name: "provider-eu")
}

​
addIpToProvider

Append an IP to a provider’s list and cascade the change through all pools and targets that reference this provider. 
mutation {
  addIpToProvider(provider: "provider-us", address: "10.0.0.5:3128") {
    name
    ipList
  }
}

​
removeIpFromProvider

Remove an IP from a provider’s list and cascade the change. The IP drains naturally from live pool queues — it is not forcibly evicted mid-request. 
mutation {
  removeIpFromProvider(provider: "provider-us", address: "10.0.0.1:3128") {
    name
    ipList
  }
}

​
Input types

​
TargetInput

FieldTypeDefaultDescription
nameStringrequiredUnique target name
regexStringrequiredPython regex matched against the full destination URL
poolNameStringrequiredName of an existing pool in the repository
minRequestIntervalFloat1.0Seconds an IP is held off the pool after each request
maxQueueWaitFloat30.0Seconds to wait for a free IP before returning 503
numRetriesInt3Retry attempts on failure
ipFailuresUntilQuarantineInt5Consecutive failures before quarantine
quarantineTimeFloat120.0Quarantine duration in seconds
mutableBooleantrueWhether this target can be updated or removed via the API

​
IpPoolInput

FieldTypeDefaultDescription
nameStringrequiredUnique pool name
ipRequests[IpRequestInput]requiredOne or more provider IP requests
mutableBooleantrueWhether this pool can be updated or removed via the API

​
IpRequestInput

FieldTypeDescription
providerStringName of an existing provider
countIntNumber of IPs to draw from the provider (takes first N; graceful if provider has fewer)

​
ProviderInput

FieldTypeDefaultDescription
nameStringrequiredUnique provider name
ipList[String]requiredProxy addresses in host:port format
regionTagString—Region label for Prometheus metrics
mutableBooleantrueWhether this provider can be updated or removed via the API
authBasicAuthInput—Omit for open or IP-whitelisted proxies

​
BasicAuthInput

FieldTypeDescription
usernameStringHTTP Basic auth username
passwordStringHTTP Basic auth password