Sign in

v1

latestOpenAPI 3.0.0ISC2026-07-26782347.5 KB
agents

Updates or creates a new agent. If an id is provided, the corresponding agent will be updated. Otherwise, a new agent will be created.

post/agents/save

Headers

X-Phantombuster-Orgstring

ID of the org that is perfoming the operation (not necessary when using a third party key)

Request body

idstring

If set, the agent with the corresponding id will be updated.

orgstring nullable

If set, the upserted agent will be linked to the specified organization.

scriptstring nullable

If set, the upserted agent will be assigned to the specified script.

branchstring nullable

If set, the upserted agent will be assigned to the specified branch.

environment'staging' | 'release' nullable

If set, the upserted agent will be assigned to the specified environment.

namestring nullable

Name of the agent.

executionTimeLimitnumber nullable

When set, the execution time of the agent will be limited by the provided value. If this limit is exceeded, the agent will be stopped.

fileMgmt'folders' | 'mix' | 'delete' nullable

Agent file management type. The type 'folders' means create new files. The type 'mix' means combine new and previous files. The type 'delete' means delete previous files.

fileMgmtMaxFoldersnumber nullable

Max amount of folders for file management.

maxParallelismnumber nullable

Sets the maximum amount of concurrent executions of the agent.

maxRetryNumbernumber nullable

Sets the maximum amount of retries the agent will do before aborting.

launchType'manually' | 'repeatedly' | 'once' | 'after agent'

Sets how the agent will be launched. Either "manually", "repeatedly", "once" or "after agent".

launchOnceAtnumber nullable

Must be set when launchType is set to "once". Sets the launch time of the agent.

launchAfterAgentIdstring nullable

Must be set when launchType is set to "after agent". Sets the id of the agent which will trigger the launch of this agent.

proxyType'none' | 'http' | 'pool' | 'squid lease'

If set to "none", no proxy will be used. If set to "http" a single http proxy will be used. If set to "pool" the proxies from the pool will be used.

proxyAddressstring nullable

When "proxyType" is set to "http", this should be the http address of the proxy. When set to "pool" this should be the name of the proxy pool you wish to use.

proxyUsernamestring nullable

Sets the username used to authenticate the proxy. Should be used when "proxyType" is set to "http".

proxyPasswordstring nullable

Sets the password used to authenticate the proxy. Should be used when "proxyType" is set to "http".

agentObjectstring nullable

Sets the agent's object. Should be a JSON string.

repeatedLaunchPreset'Once every other day' | 'Once per day' | 'Once per day, at the start of the day' | 'Twice per day' | 'Thrice per day' | '4 times per day' | '6 times per day' | '8 times per day' | 'Once every other hour' | 'Once per hour' | 'Twice per hour' | 'Thrice per hour' | '4 times per hour' | 'Once every other working hour' | 'Once per working hour' | 'Twice per working hour' | 'Thrice per working hour' | '4 times per working hour' | 'Once every other working hour, excluding weekends' | 'Once per working hour, excluding weekends' | 'Twice per working hour, excluding weekends' | 'Thrice per working hour, excluding weekends' | '4 times per working hour, excluding weekends' nullable

Automatically sets the agent's launch schedule according to a preset.

applyScriptManifestDefaultSettingsboolean

If true, the manifest's default settings will be applied to the agent.

masterAgentLaunchAfternumber nullable

Defines when the agent will launch once a slave agent finishes. When not set, the platform chooses a value between 10 and 15 minutes randomly.

persistedVolumeKeystring nullable

Key identifying the persisted volume to attach to the agent's containers.

wasSetupValidWhenSubmittedByTheFrontendboolean

If true, the agent's setup is considered complete.

shouldPropagateUpdatedSettingsToWorkersRegardlessOfSessionTypeboolean

If true, the updated settings will be propagated to the workers regardless of the session type.

expireAtnumber nullable

The date when the agent will be deleted.

idempotencyKeystring nullable

Optional key for idempotent operations - only for creating an agent.

internalMetadataobject nullable

Key-value pairs reserved for PhantomBuster internal use.

userCustomMetadataobject nullable

User-defined key-value pairs for tagging and filtering agents.

Response

Agent updated or inserted successfully.

idstring required