Promote Agent to Production

POST

agents

{agent_id}

promote

curl --request POST \
  --url https://api.bland.ai/v2/agents/{agent_id}/promote \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "version_id": "<string>",
  "branch_id": "<string>",
  "bump": "<string>",
  "force": true,
  "expected_staging_version_id": "<string>"
}
'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/promote"

payload = {
    "version_id": "<string>",
    "branch_id": "<string>",
    "bump": "<string>",
    "force": True,
    "expected_staging_version_id": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    version_id: '<string>',
    branch_id: '<string>',
    bump: '<string>',
    force: true,
    expected_staging_version_id: '<string>'
  })
};

fetch('https://api.bland.ai/v2/agents/{agent_id}/promote', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/promote",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'version_id' => '<string>',
    'branch_id' => '<string>',
    'bump' => '<string>',
    'force' => true,
    'expected_staging_version_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/{agent_id}/promote"

	payload := strings.NewReader("{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/promote")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/{agent_id}/promote")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "semver": "1.4.0",
    "environments": [
      {
        "id": "3d5a2d9b-0457-4610-b6d0-86d09b42d8bc",
        "env_type": "dev",
        "current_version_id": null
      },
      {
        "id": "f1ad8610-caea-4c4f-9d9b-3f35bf1a1a43",
        "env_type": "staging",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      },
      {
        "id": "de65595f-4fbf-4d9e-9ce4-13dd995e863e",
        "env_type": "production",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      }
    ],
    "production_moved": true
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "CHECKS_BLOCKED",
      "message": "A required evaluation failed. Promotion is blocked"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "STAGING_UNPINNED",
      "message": "Publish to staging before promoting to production"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Agent not found"
    }
  ]
}

Overview

Moves the agent’s production pointer and records a deployment. Phone numbers attached to the agent begin answering with the promoted version, and any active experiment whose baseline is production ends with completed_reason set to baseline_changed.

With an empty body, production moves to whatever staging is pinned to. The deployment carries that version’s original semver; no new number is minted.
With version_id, that exact version goes to production, from the dev timeline or an open branch. staging is repointed to it in the same step. A version that was never published is given a semver using bump.

The server does not run evaluations, but it enforces them. When the staging evaluation configuration has at least one required evaluation, the promote checks the newest staging check run that scored the version being promoted. It returns 409 CHECKS_BLOCKED when there is no such run, when the run is still in progress, errored, or was cancelled, when a required evaluation failed, or when the run used a different configuration than the one saved now. Start a run on staging with Start Check Run before you promote, or send force: true to skip the check for this one promote. A version that references an environment variable with no production value is refused with 409 AGENT_VARIABLE_UNRESOLVED, even with force. Requires an admin, owner, operator, or prompter role.

Headers

string

required

Your API key for authentication.

Path Parameters

string

required

The agent’s unique identifier.

Body Parameters

All body parameters are optional.

string

ID of a version of this agent to promote instead of the staging pin. It can be on the dev timeline or on an open branch. Returns 404 VERSION_NOT_FOUND if the ID is not one of this agent’s versions, and 409 BRANCH_CLOSED if its branch was merged or archived.

string

The branch you are promoting from. When set, version_id must be a version saved on that branch, or the request returns 404 VERSION_NOT_FOUND. Sending branch_id without version_id returns 400 INVALID_BRANCH.

string

default:"patch"

Which component to increment when version_id names a version that was never published: patch, minor, or major. Ignored otherwise. Returns 400 INVALID_BUMP for any other value.

boolean

default:"false"

Skip the required-evaluation check for this one promote. Also promotes while a migration rollout from a V1 pathway to this agent is live, which otherwise returns 409 ROLLOUT_IN_PROGRESS. The audit log records the bypass; the deployment does not. Does not skip the variable check. A non-boolean value returns 400 INVALID_FORCE.

string

The staging version you reviewed. Applies only without version_id. If staging points at a different version when the promote runs, nothing changes and the request returns 409 STAGING_CHANGED. Sending it with version_id, or as an empty or non-string value, returns 400 INVALID_EXPECTED_STAGING_VERSION.

Response

Returns 200 on success.

string

The promoted version’s number, for example 1.4.0.

array

The agent’s three environments after the promote. Each has id, env_type (dev, staging, or production), and current_version_id (the pinned version, or null if unpinned). staging and production now point at the same version.

boolean

false when production already pinned the version named by version_id and only staging moved to match it. true otherwise.

null | array

null on success, or a list of error objects if the request failed. Besides the errors above, returns 400 STAGING_UNPINNED when the body has no version_id and nothing has been published to staging, 400 ALREADY_IN_PRODUCTION when production and staging already pin the version, and 409 PUBLISH_IN_PROGRESS when another publish or promote for the same agent is running; retry after a moment. It returns 409 REPOSITORY_RELEASE_REQUIRED for an agent connected to a GitHub repository, which releases through the repository instead, and 503 AGENT_KNOWLEDGE_RUNTIME_UNAVAILABLE when the version uses knowledge source variables that your organization’s call runtime can’t run yet.

{
  "data": {
    "semver": "1.4.0",
    "environments": [
      {
        "id": "3d5a2d9b-0457-4610-b6d0-86d09b42d8bc",
        "env_type": "dev",
        "current_version_id": null
      },
      {
        "id": "f1ad8610-caea-4c4f-9d9b-3f35bf1a1a43",
        "env_type": "staging",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      },
      {
        "id": "de65595f-4fbf-4d9e-9ce4-13dd995e863e",
        "env_type": "production",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      }
    ],
    "production_moved": true
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "CHECKS_BLOCKED",
      "message": "A required evaluation failed. Promotion is blocked"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "STAGING_UNPINNED",
      "message": "Publish to staging before promoting to production"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Agent not found"
    }
  ]
}

Docs for agents: llms.txt

⌘I

Promote Agent to Production

curl --request POST \
  --url https://api.bland.ai/v2/agents/{agent_id}/promote \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "version_id": "<string>",
  "branch_id": "<string>",
  "bump": "<string>",
  "force": true,
  "expected_staging_version_id": "<string>"
}
'

import requests

url = "https://api.bland.ai/v2/agents/{agent_id}/promote"

payload = {
    "version_id": "<string>",
    "branch_id": "<string>",
    "bump": "<string>",
    "force": True,
    "expected_staging_version_id": "<string>"
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    version_id: '<string>',
    branch_id: '<string>',
    bump: '<string>',
    force: true,
    expected_staging_version_id: '<string>'
  })
};

fetch('https://api.bland.ai/v2/agents/{agent_id}/promote', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/promote",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'version_id' => '<string>',
    'branch_id' => '<string>',
    'bump' => '<string>',
    'force' => true,
    'expected_staging_version_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v2/agents/{agent_id}/promote"

	payload := strings.NewReader("{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v2/agents/{agent_id}/promote")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v2/agents/{agent_id}/promote")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version_id\": \"<string>\",\n  \"branch_id\": \"<string>\",\n  \"bump\": \"<string>\",\n  \"force\": true,\n  \"expected_staging_version_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "semver": "1.4.0",
    "environments": [
      {
        "id": "3d5a2d9b-0457-4610-b6d0-86d09b42d8bc",
        "env_type": "dev",
        "current_version_id": null
      },
      {
        "id": "f1ad8610-caea-4c4f-9d9b-3f35bf1a1a43",
        "env_type": "staging",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      },
      {
        "id": "de65595f-4fbf-4d9e-9ce4-13dd995e863e",
        "env_type": "production",
        "current_version_id": "46201abd-c8e6-4095-a65f-d5135a673627"
      }
    ],
    "production_moved": true
  },
  "errors": null
}

{
  "data": null,
  "errors": [
    {
      "error": "CHECKS_BLOCKED",
      "message": "A required evaluation failed. Promotion is blocked"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "STAGING_UNPINNED",
      "message": "Publish to staging before promoting to production"
    }
  ]
}

{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Agent not found"
    }
  ]
}