Update Proxy

POST

api

instance

proxy

:instance

Update Proxy

curl --request POST \
  --url https://api.example.com/api/instance/proxy/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "enabled": true,
  "host": "<string>",
  "port": "<string>",
  "protocol": "<string>",
  "username": "<string>",
  "password": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    enabled: true,
    host: '<string>',
    port: '<string>',
    protocol: '<string>',
    username: '<string>',
    password: '<string>'
  })
};

fetch('https://api.example.com/api/instance/proxy/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/instance/proxy/:instance"

payload = {
    "enabled": True,
    "host": "<string>",
    "port": "<string>",
    "protocol": "<string>",
    "username": "<string>",
    "password": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: yes

Description

Sets an HTTP, HTTPS, or SOCKS5 proxy specific to the instance. The configuration only takes effect after /reconnect or a new /connect.

Examples

Authenticated SOCKS5

Configures a SOCKS5 proxy on port 1080 with user and password. The password is encrypted at-rest with AES-256-GCM and never returns in plaintext in the response.

curl -X POST "https://ryzeapi.cloud/api/instance/proxy/my-instance" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "host": "proxy.example.com",
    "port": "1080",
    "protocol": "socks5",
    "username": "user1",
    "password": "secret"
  }'

await fetch("https://ryzeapi.cloud/api/instance/proxy/my-instance", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    enabled:  true,
    host:     "proxy.example.com",
    port:     "1080",
    protocol: "socks5",
    username: "user1",
    password: "secret"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/proxy/my-instance",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "enabled":  True,
        "host":     "proxy.example.com",
        "port":     "1080",
        "protocol": "socks5",
        "username": "user1",
        "password": "secret"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "enabled":  true,
        "host":     "proxy.example.com",
        "port":     "1080",
        "protocol": "socks5",
        "username": "user1",
        "password": "secret"
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/proxy/my-instance", body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

HTTP without auth

Points to an internal HTTP proxy (10.0.0.5:3128) without credentials, common scenario in corporate networks with auth-by-IP or open proxy.

curl -X POST "https://ryzeapi.cloud/api/instance/proxy/my-instance" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"host":"10.0.0.5","port":"3128","protocol":"http"}'

await fetch("https://ryzeapi.cloud/api/instance/proxy/my-instance", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    enabled:  true,
    host:     "10.0.0.5",
    port:     "3128",
    protocol: "http"
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/proxy/my-instance",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "enabled":  True,
        "host":     "10.0.0.5",
        "port":     "3128",
        "protocol": "http"
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"enabled":true,"host":"10.0.0.5","port":"3128","protocol":"http"}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/proxy/my-instance", body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Disable

Sends only enabled: false to remove the individual proxy from the instance. It goes back to using the deploy global proxy (if any) or a direct connection on the next reconnection.

curl -X POST "https://ryzeapi.cloud/api/instance/proxy/my-instance" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

await fetch("https://ryzeapi.cloud/api/instance/proxy/my-instance", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ enabled: false })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/instance/proxy/my-instance",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={"enabled": False}
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{"enabled":false}`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/instance/proxy/my-instance", body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Success response

200 OK

{
  "success": true,
  "message": "Proxy configuration updated successfully",
  "proxy": {
    "enabled": true,
    "host": "proxy.example.com",
    "port": "1080",
    "protocol": "socks5",
    "username": "user1",
    "password": ""
  }
}

The password appears as an empty string ("") in the response, the server never returns the password in plaintext.

Path parameters

string

required

Instance name.

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json.

Request body

boolean

required

Enables/disables the instance proxy.

string

IP or hostname. Required if enabled=true.

string

Port as a string ("1080", "8080"). Required if enabled=true.

string

"http", "https", or "socks5". Required if enabled=true.

string

User (optional).

string

Password (optional, encrypted at-rest).

Rules

enabled=true requires host, port, and protocol.
protocol must be http, https, or socks5.
username / password are optional (open proxy or auth-by-IP).
enabled=false makes the instance go back to using the default deploy proxy (if any).
The password is encrypted at-rest (AES-256-GCM) and redacted in the response.

Notes

The instance individual proxy has priority over the deploy global proxy. If enabled=false, the instance uses the global proxy (if any) or a direct connection.

Proxy changes do not reconnect automatically, call reconnect to apply.

Errors

HTTP	`error.message`	When
400	`Invalid request body`	Malformed JSON.
400	`Host is required when proxy is enabled`	`enabled=true` without `host`.
400	`Port is required when proxy is enabled`	`enabled=true` without `port`.
400	`Protocol is required when proxy is enabled`	`enabled=true` without `protocol`.
400	`Protocol must be one of: http, https, socks5`	`protocol` outside the enum.
401	`Invalid token`	Token missing or invalid.
404	`Instance not found`	Name does not exist.
429	`Rate limit exceeded. Try again later.`	More than 100 req/min.
500	`Failed to update proxy configuration`	Database error.

{
  "success": false,
  "error": {
    "message": "Protocol must be one of: http, https, socks5"
  }
}

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

Examples

Authenticated SOCKS5

HTTP without auth

Disable

Success response

Path parameters

Headers

Request body

Rules

Notes

Errors

​Description

​Examples

​Authenticated SOCKS5

​HTTP without auth

​Disable

​Success response

​Path parameters

​Headers

​Request body

​Rules

​Notes

​Errors

Description

Examples

Authenticated SOCKS5

HTTP without auth

Disable

Success response

Path parameters

Headers

Request body

Rules

Notes

Errors