GraphQL API

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
  }
}

`targetMetrics(name: String!)`

Aggregate request metrics for one target — total/success/failed request counts, average latency, and (in-process source only) the last request timestamp. Backs the admin UI’s per-target metrics panel.

{
  targetMetrics(name: "google-apis") {
    name
    totalRequests
    successRequests
    failedRequests
    avgLatencyMs
    lastRequestAt
  }
}

Returns null if neither metrics source is available for this deployment (see Admin UI metrics panel for when that happens and how to fix it).

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. Cascades the updated IP list through all pools and targets that reference this provider.

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

Field	Type	Default	Description
`name`	String	required	Unique target name
`regex`	String	required	Python regex matched against the full destination URL
`poolName`	String	required	Name of an existing pool in the repository
`minRequestInterval`	Float	`1.0`	Seconds an IP is held off the pool after each request
`maxQueueWait`	Float	`30.0`	Seconds to wait for a free IP before returning 503
`numRetries`	Int	`3`	Retry attempts on failure
`ipFailuresUntilQuarantine`	Int	`5`	Consecutive failures before quarantine
`quarantineTime`	Float	`120.0`	Quarantine duration in seconds
`defaultProxyPort`	Int	`8080`	Port used when a pool IP has no explicit port
`spoofUserAgent`	Boolean	`true`	Replace `User-Agent` with a random browser UA
`mutable`	Boolean	`true`	Whether this target can be updated or removed via the API
`static`	Boolean	`false`	When `true`, the target is treated as config-owned and rejects API mutations

IpPoolInput

Field	Type	Default	Description
`name`	String	required	Unique pool name
`ipRequests`	[IpRequestInput]	required	One or more provider IP requests
`mutable`	Boolean	`true`	Whether this pool can be updated or removed via the API
`static`	Boolean	`false`	When `true`, the pool is treated as config-owned and rejects API mutations

IpRequestInput

Field	Type	Description
`provider`	String	Name of an existing provider
`count`	Int	Number of IPs to draw from the provider (takes first N; graceful if provider has fewer)

ProviderInput

Field	Type	Default	Description
`name`	String	required	Unique provider name
`ipList`	[String]	required	Proxy addresses in `host:port` format
`regionTag`	String	—	Region label for Prometheus metrics
`mutable`	Boolean	`true`	Whether this provider can be updated or removed via the API
`static`	Boolean	`false`	When `true`, the provider is treated as config-owned and rejects API mutations
`auth`	BasicAuthInput	—	Omit for open or IP-whitelisted proxies

BasicAuthInput

Field	Type	Description
`username`	String	HTTP Basic auth username
`password`	String	HTTP Basic auth password

Getting Started

Concepts

For Administrators

For Developers

For Contributors

Cascade behaviour

Queries

`targets`

`target(name: String!)`

`pools`

`pool(name: String!)`

`providers`

`provider(name: String!)`

`status`

`targetMetrics(name: String!)`

Mutations

Target mutations

`addTarget`

`updateTarget`

`removeTarget`

Pool mutations

`addPool`

`updatePool`

`removePool`

Provider mutations

`addProvider`

`updateProvider`

`removeProvider`

`addIpToProvider`

`removeIpFromProvider`

Input types

TargetInput

IpPoolInput

IpRequestInput

ProviderInput

BasicAuthInput

​Cascade behaviour

​Queries

​targets

​target(name: String!)

​pools

​pool(name: String!)

​providers

​provider(name: String!)

​status

​targetMetrics(name: String!)

​Mutations

​Target mutations

​addTarget

​updateTarget

​removeTarget

​Pool mutations

​addPool

​updatePool

​removePool

​Provider mutations

​addProvider

​updateProvider

​removeProvider

​addIpToProvider

​removeIpFromProvider

​Input types

​TargetInput

​IpPoolInput

​IpRequestInput

​ProviderInput

​BasicAuthInput

Cascade behaviour

Queries

`targets`

`target(name: String!)`

`pools`

`pool(name: String!)`

`providers`

`provider(name: String!)`

`status`

`targetMetrics(name: String!)`

Mutations

Target mutations

`addTarget`

`updateTarget`

`removeTarget`

Pool mutations

`addPool`

`updatePool`

`removePool`

Provider mutations

`addProvider`

`updateProvider`

`removeProvider`

`addIpToProvider`

`removeIpFromProvider`

Input types

TargetInput

IpPoolInput

IpRequestInput

ProviderInput

BasicAuthInput