Browse documentation

Deployments

Check a deployment before creating it

Asks the refusals only the server knows, without writing anything, so a deploy that would be refused stops before it changes the agent or one of its variables. Requires agents:write. The CLI calls it first; an API that does not have it answers 404 or 405, and the CLI goes on as it did before.

It takes the agent's slug (the agent may not exist yet), the runtime policy the deployment will be created with, and the variables the deploy is about to set, by name and kind. It never takes a value. It judges, in this order, and answers each refusal with the code and message the create call answers it with:

an archived agent holding the slug: 409, code conflict;
when the request has deploying and the workspace has the credential broker on: an agent with secrets in the old format, a secret variable exposed to the sandbox or a secret a credential exchange names, 409, code credentials_migration_required, with a sentence naming each one. The variables sent replace the agent's of the same name;
a credential-exchange secret that will not exist, will not be a secret, will not be exposed to the sandbox or will not allow the exchange host: 400, code invalid_request. The variables sent count as set, and so do those the agent already holds;
a sandbox size the workspace's plan leaves out: 403, code permission_denied, with the plan sentence;
a workspace with its four deployments already queued or building: 429, code rate_limited, with Retry-After.

Before those, when the request names the agent's model: a built-in provider's model the engine's model library no longer includes answers 400, code invalid_request, param model, with a sentence that names a model to choose instead, the settings file in agentFolder to choose it in, and the way to keep it as a custom provider. A model on a provider listed in customProviderIds, on a provider the library does not have, or of an agent with extensions (hasExtensions, which may register any provider) is never refused; azure-openai-responses/<model> is judged as azure/<model>.

200 means none of those would refuse the deploy now. It is not a reservation: another deploy may take the last place before this one creates its deployment, and the create call decides.

POST/deployments/validate

Authorization

AuthorizationBearer <token>

Headers

Salambo-Clientstring

Which published Salambo client sent the request, as cli/<version> or sdk/<version>. The CLI and SDK send it on every request; a request without it, or with a value in another shape, is served as usual. The API refuses a CLI below its minimum supported version with 426.

maxLength: 100

Bodyrequired

application/json

object

Additional properties are not allowed.

agentSlugstringrequired

The agent the deploy updates, or creates when none has this slug.

pattern: "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$"

runtimeConfigobjectrequired

Additional properties are not allowed.

Show nested schema

sandboxRegionstring

enum: ["us","eu"]

sandboxSizestring

The sandbox size. Small unless named; Large is on Business.

enum: ["s","m","l","small","medium","large"]

egressPolicyModestringrequired

enum: ["restricted","full-open"]

egressAllowlistarrayrequired

maxItems: 100

Show nested schema

Array items

string

credentialExchangesobject

maxProperties: 10

Show nested schema

Additional properties

object

Additional properties are not allowed.

requestobjectrequired

Additional properties are not allowed.

Show nested schema

hoststringrequired

methodstringrequired

const: "POST"

pathstringrequired

maxLength: 2048

contentTypestringrequired

const: "application/x-www-form-urlencoded"

requiredFieldsobjectrequired

minProperties: 1
maxProperties: 8

Show nested schema

Additional properties

string

maxLength: 256

secretFieldsobjectrequired

minProperties: 1
maxProperties: 4

Show nested schema

Additional properties

string

pattern: "^[A-Z][A-Z0-9_]{0,127}$"

responseobjectrequired

Additional properties are not allowed.

Show nested schema

contentTypestringrequired

const: "application/json"

credentialFieldstringrequired

tokenTypeFieldstringrequired

expectedTokenTypestringrequired

const: "Bearer"

expiresInFieldstringrequired

accessobjectrequired

Additional properties are not allowed.

Show nested schema

allowedHostsarrayrequired

minItems: 1
maxItems: 25
uniqueItems: true

Show nested schema

Array items

string

workspaceUpgradePolicystringrequired

enum: ["automatic","new-run-only"]

otlpEndpointOverridestring | null

format: "uri"

otelIncludeContentOverrideboolean | null

variablesarrayrequired

The variables the deploy is about to set. Names and kinds only, never values.

maxItems: 500

Show nested schema

Array items

object

Additional properties are not allowed.

namestringrequired

maxLength: 100
pattern: "^[A-Z][A-Z0-9_]*$"

isSecretbooleanrequired

allowedHostsarray

Show nested schema

Array items

string

exposeToarray

minItems: 1
default: ["runtime","sandbox"]

Show nested schema

Array items

string

enum: ["runtime","sandbox"]

modelobject

The model the agent's settings name. Absent, the model is not judged.

Additional properties are not allowed.

Show nested schema

providerstringrequired

minLength: 1
maxLength: 200

modelIdstringrequired

minLength: 1
maxLength: 200

customProviderIdsarray

The providers the agent's settings declare; their models are never refused.

maxItems: 100
default: []

Show nested schema

Array items

string

minLength: 1
maxLength: 200

hasExtensionsboolean

Whether the agent has extensions. An extension may register any provider at the Turn, so with one the model is not judged.

default: false

agentFolderstring

The folder the project keeps its agent in. A refused model's sentence names the settings file in it.

enum: [".pi",".salambo"]
default: ".pi"

deployingboolean

The request is a deploy's, so an agent with secrets in the old format is refused. A command that only reads the switches leaves it out.

default: false

Response

application/json

Nothing refuses the deploy now

object

objectstringrequired

const: "deployment.preflight"

okbooleanrequired

const: true

featuresobject

The deploy features of the caller's workspace, each on or off. A client that does not know a name ignores it; an absent name is off.

Show nested schema

salambo_layoutboolean

The agent may live in .salambo/ instead of .pi/.

salambo_devboolean

Whether salambo dev is available to the workspace.

Additional properties

boolean

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/deployments/validate' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '@request.json'

Replace placeholders before running. JSON templates without a sample body read your payload from request.json.

Response

{
  "object": "deployment.preflight",
  "ok": true,
  "features": {
    "salambo_layout": true,
    "salambo_dev": true
  }
}