Proxies and agents

Create a pool

POST /api/v1/proxy-pools

{"code":"catalog-proxies","name":"Catalog proxies","rotation":"round_robin"}

Rotation supports round_robin, random, fastest, least_used, or sticky. Omit code to generate it automatically. For sticky, sticky_seconds accepts 60–86400 seconds, default 600. Codes are unique per workspace and immutable. Editing proxies requires permission to manage settings; viewing them requires connection read access.

Add an address

POST /api/v1/proxies

{"pool_id":1,"scheme":"http","host":"proxy.example.invalid","port":8080,"username":"account","password":"REPLACE_ME"}

Schemes are http and socks5. HTTPS target sites work through HTTP CONNECT; HTTPS proxy endpoints are unsupported; ports range from 1 to 65535. Username and password are optional. The password is stored encrypted and cannot be read back. The pool must belong to the key's workspace.

For bulk import, send pool_id and a text string to POST /proxies/import. The response reports addresses added and entries skipped, with reasons. Partial success is not a complete import.

Assign a pool to a site with PATCH /sites/{id} and {"proxy_pool_id":1}. Test one address through POST /proxies/{id}/check or a whole pool through /proxy-pools/{id}/check. These are real network checks. Use /unban to lift a temporary ban.

The interface tests groups in small background batches. The synchronous external /proxy-pools/{id}/check method accepts at most five addresses. Larger groups return 422 with code use_background_check; open the group in the interface and start its background test.

Agents

GET /api/v1/agents lists accessible agents; GET /api/v1/agents/{id} returns one agent's details and status. Reading agents requires the corresponding permission.

The external API cannot create or delete agents, deploy one over SSH, retrieve an agent token, or submit internal results on an agent's behalf. Those operations belong to the internal protocol.

To use an agent already configured in the platform, set execution_target: "agent" and agent_id on the site, then start a normal run. Read its status and synchronized results through /runs and /sites/{id}/records. You do not need the agent's address or internal secrets.