Batch operations

Use batch operations after the individual resource endpoints are familiar. A batch can create, update, and remove servers and tweaks in one configuration. It does not create the configuration itself.

Sync resources

POST /api/v1/configs/{config_key}/sync

Use the owner's Client API key. Save this as batch.json, replacing the configuration and resource keys with values returned by the API:

{
  "servers": [
    {"unique_key": "YOUR_SERVER_UNIQUE_KEY", "name": "Primary SSH"}
  ],
  "tweaks": [
    {"unique_key": "YOUR_TWEAK_UNIQUE_KEY", "note": "Updated by my backend"}
  ],
  "list_resources": true
}

curl --fail-with-body --request POST "$API_BASE/configs/$CONFIG_KEY/sync" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY" \
  --data-binary @batch.json

The configuration key belongs only in the URL. Do not include config_unique_key, config_key, or remove_config in this body; delete configurations through their dedicated endpoints.

At least one resource operation or list_resources: true is required. Omit a resource's unique_key to create it with a generated key. A matching key updates the resource; a new unused key can create one when all required creation fields are supplied. A key already used by another configuration is rejected.

Transaction and response

Removals run first, followed by server upserts and tweak upserts. If any operation fails validation, all resource changes in that request roll back. This lets you remove a resource before creating its replacement without exceeding the account's resource count limit.

HTTP 200 returns configuration_id, configuration_name, config_unique_key, summary, servers, tweaks, and resource_list. The latter is null unless requested. The summary counts servers_created, servers_updated, servers_deleted, tweaks_created, tweaks_updated, and tweaks_deleted. Each mutation result includes its action and unique_key.

A 422 response contains indexed errors such as servers.0.name. A failed batch can still consume a Client API quota unit. See limits.

Delete several configurations

POST /api/v1/configs/remove

This permanently deletes saved configurations and their dependent resources.

{
  "config_unique_keys": [
    "FIRST_CONFIGURATION_UNIQUE_KEY",
    "SECOND_CONFIGURATION_UNIQUE_KEY"
  ]
}

Send 1–100 distinct keys, each no more than 64 characters. Only configurations owned by your account are deleted. Missing keys and keys not owned by the account are counted as not found. The response reports deleted and not_found counts; inspect them before assuming all requested configurations were removed.

For one configuration, use DELETE a configuration.

Protected resources

Internal servers and tweaks expose only basic identity/display information. You may remove them using remove_servers or remove_tweaks, but cannot include their keys in upsert arrays. An attempted edit returns 403 and rolls back the entire batch, even if the same key also appears in a removal array. Removal responses and resource_list never reveal their connection details.

Telegram and scheduled processes

Telegram configuration management uses the same Client API, authenticated with the key linked by the bot user. It lists configurations and resources, fetches full details before editing, creates servers/tweaks with POST, edits with PATCH, and deletes with DELETE. Device/password creation uses the bulk access endpoints and deletion uses numeric access-record IDs. The bot reads the singular server creation response to offer Add matching tweak.

The bot does not automatically retry mutations after a network/server error: a lost response might already have created the resource. Refresh its list before submitting again. Read requests can retry transient failures. Each API attempt is subject to the same ownership checks, daily quota, and burst limits as your own backend.

The panel's scheduled processes use these workflows:

Catalog sync is the deliberate upsert workflow. Workers submit servers, optional tweaks, and removal arrays; they read summary counters from the batch response. They never create the parent configuration. Configure a Client API credential owned by that configuration's account.

Public-server catalog workers that save directly through panel models do not call these Client API endpoints. The first-party mobile apps also use their separate signed import/update flow, not Telegram's API-key management calls. For operator commands and dry-run support, see the repository's app/Console/Processes/README.md.

Telegram shows protected resources as “removal only,” omits the Update action, and resolves deletion from their basic list information. Manually triggering an edit callback cannot bypass API protection.