Generate a configuration

The Business API turns a JSON document into text that the app can import. Use it when your backend owns the source data and you want to generate a configuration on demand.

POST /api/business/v1/config/generate

You need a Business API key. A Client API key does not work here.

1. Build a small configuration

Use this JSON with your own SSH host and credentials. Saving it to a file is optional.

{
    "name": "My first configuration",
    "servers": [
        {
            "name": "My SSH server",
            "tunnel": {
                "family": "ssh",
                "variant": "default"
            },
            "carrier": {
                "type": "default",
                "settings": {}
            },
            "accepted_methods": [
                []
            ],
            "settings": {
                "endpoint": {
                    "hosts": [
                        "ssh.example.com"
                    ],
                    "ports": [
                        22
                    ]
                },
                "credentials": {
                    "username": "demo",
                    "password": "replace-me"
                }
            }
        }
    ],
    "tweaks": [
        {
            "name": "Direct SSH",
            "tunnels": {
                "ssh": {
                    "variants": [
                        "default"
                    ]
                }
            },
            "carrier": {
                "type": "default",
                "settings": {}
            },
            "methods": {}
        }
    ]
}

The server structure is the same public connection format used by the Client API. See connection examples for other protocols.

2. Generate the import text

Send the configuration directly as a raw JSON request body with Content-Type: application/json. No file is required. In Postman, select Body → raw → JSON and paste the configuration JSON. In your backend, serialize the configuration object as JSON and send it as the request body.

export BUSINESS_API_KEY='YOUR_BUSINESS_API_KEY'
curl --fail-with-body --request POST 'https://httptweak.com/api/business/v1/config/generate' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $BUSINESS_API_KEY" \
  --data-raw '
{
    "name": "My first configuration",
    "servers": [
        {
            "name": "My SSH server",
            "tunnel": {
                "family": "ssh",
                "variant": "default"
            },
            "carrier": {
                "type": "default",
                "settings": {}
            },
            "accepted_methods": [
                []
            ],
            "settings": {
                "endpoint": {
                    "hosts": [
                        "ssh.example.com"
                    ],
                    "ports": [
                        22
                    ]
                },
                "credentials": {
                    "username": "demo",
                    "password": "replace-me"
                }
            }
        }
    ],
    "tweaks": [
        {
            "name": "Direct SSH",
            "tunnels": {
                "ssh": {
                    "variants": [
                        "default"
                    ]
                }
            },
            "carrier": {
                "type": "default",
                "settings": {}
            },
            "methods": {}
        }
    ]
}
'

Alternatively, save the JSON above as configuration.json and use the command below. --data-binary @configuration.json reads the local file and sends its contents as the same raw JSON body; it does not upload a file using multipart/form-data.

export BUSINESS_API_KEY='YOUR_BUSINESS_API_KEY'
curl --fail-with-body --request POST 'https://httptweak.com/api/business/v1/config/generate' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $BUSINESS_API_KEY" \
  --data-binary @configuration.json

On success, HTTP 200 has Content-Type: text/plain; charset=UTF-8. The body is the importable configuration itself. Copy it into the app's configuration import flow. Accept: application/json makes validation errors predictable; successful generation still returns plain text.

To save a successful response, use your backend's HTTP status check before writing it as a configuration file. Do not pass an error JSON body to the app as import text.

Request fields

Each server needs name, tunnel, carrier, accepted_methods, and settings. Each tweak needs name, tunnels, carrier, and methods. Both support optional category and note. Their name/category limits are 100 characters, and notes allow 255 characters.

Messages support the placeholders below; values are resolved while the generated configuration is built.

The generator assigns fresh configuration and resource keys. Do not submit unique_key, database IDs, or an owner username. The owner username comes from your Business API account; version information comes from the installation's settings.

What success means

The configuration is built in memory. It is not saved to your panel's configuration list, and its generated key cannot be used with Client API resource endpoints.

Each valid generation consumes one daily unit after validation, including a request that subsequently fails during generation or delivery. Repeating the request generates a fresh configuration and consumes another unit. There is no idempotency-key mechanism.

Add features gradually

• Delivery & Cloud Protect explains cloud links and one-time imports.
• Configuration settings covers local locks, expiration, and editing permissions.
• Responses, errors & limits explains quota and validation failures.

Cloud password, cloud hardware-lock, and cloud update modes require a saved panel configuration and cannot be enabled on generated configurations.

Generation is not an update endpoint

Every call creates a new configuration key and new server/tweak keys, even when you send the same name and connection details. Import the new result as a new configuration. Do not point an imported configuration's update URL at this generation endpoint: app update requests require the original key, and generation requires your private Business credential.

Use a saved panel configuration with cloud updates and the Client API when you need to maintain a configuration already distributed to users. A custom update URL is useful only if your own publishing process can serve a valid same-key export.

Generation validates document structure, not remote connectivity or whether a server/tweak pair matches. Empty resource arrays and tweak-only exports can be valid, but the apps need both a selected tweak and a compatible server to connect. Both resources must use a compatible carrier, tunnel variant, accepted method set, and category. Empty categories match each other; named categories need a shared token (case-insensitive, separated by semicolons or newlines).