Create an agent version

POST

agents

{agent_id_or_name}

versions

curl --request POST \
  --url https://api.guild.ai/v1/agents/{agent_id_or_name}/versions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "skip_validation": false,
  "publish": false,
  "files": null,
  "bundle": null,
  "encoding": null,
  "commit_sha": null,
  "summary": null,
  "version_number": null
}
'

import requests

url = "https://api.guild.ai/v1/agents/{agent_id_or_name}/versions"

payload = {
    "skip_validation": False,
    "publish": False,
    "files": None,
    "bundle": None,
    "encoding": None,
    "commit_sha": None,
    "summary": None,
    "version_number": None
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    skip_validation: false,
    publish: false,
    files: null,
    bundle: null,
    encoding: null,
    commit_sha: null,
    summary: null,
    version_number: null
  })
};

fetch('https://api.guild.ai/v1/agents/{agent_id_or_name}/versions', 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.guild.ai/v1/agents/{agent_id_or_name}/versions",
  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([
    'skip_validation' => false,
    'publish' => false,
    'files' => null,
    'bundle' => null,
    'encoding' => null,
    'commit_sha' => null,
    'summary' => null,
    'version_number' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$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.guild.ai/v1/agents/{agent_id_or_name}/versions"

	payload := strings.NewReader("{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	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.guild.ai/v1/agents/{agent_id_or_name}/versions")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.guild.ai/v1/agents/{agent_id_or_name}/versions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}"

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

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "author_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "validation_status": "SKIPPED",
  "dependencies": {},
  "description": "<string>",
  "env_references": [
    "<unknown>"
  ],
  "input_schema": {},
  "llm_models": [
    "<unknown>"
  ],
  "output_schema": {},
  "published_at": "2023-11-07T05:31:56Z",
  "publishing_started_at": "2023-11-07T05:31:56Z",
  "raw_tools": [
    "<unknown>"
  ],
  "runtime_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sha": "<string>",
  "summary": "<string>",
  "tools": [
    "<unknown>"
  ],
  "version_number": "<string>",
  "agent": "<unknown>",
  "author": "<unknown>",
  "status": "<unknown>",
  "version_type": "<unknown>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "author_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "validation_status": "SKIPPED",
  "dependencies": {},
  "description": "<string>",
  "env_references": [
    "<unknown>"
  ],
  "input_schema": {},
  "llm_models": [
    "<unknown>"
  ],
  "output_schema": {},
  "published_at": "2023-11-07T05:31:56Z",
  "publishing_started_at": "2023-11-07T05:31:56Z",
  "raw_tools": [
    "<unknown>"
  ],
  "runtime_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sha": "<string>",
  "summary": "<string>",
  "tools": [
    "<unknown>"
  ],
  "version_number": "<string>",
  "agent": "<unknown>",
  "author": "<unknown>",
  "status": "<unknown>",
  "version_type": "<unknown>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes.

Path Parameters

agent_id_or_name

string

required

Body

application/json

version_type

enum<string>

required

Available options:

EPHEMERAL,

COMMITTED

skip_validation

boolean

default:false

publish

boolean

default:false

Publish the version once it passes validation

files

AgentVersionFile · object[] | null

Every source file of the new version, as path and content

Show child attributes

bundle

string | null

encoding

string | null

commit_sha

string | null

summary

string | null

What changed

version_number

string | null

Response

Successful response

Option 1
Option 2

job_id

string<uuid> | null

required

The validation or publish job this request started; null when it started none.

string<uuid>

created_at

string<date-time>

updated_at

string<date-time>

agent_id

string<uuid>

author_id

string<uuid>

validation_status

enum<string>

Available options:

SKIPPED,

PENDING,

RUNNING,

PASSED,

FAILED

dependencies

object | null

npm package.json dependencies

description

string | null

Description for the agent extracted from the agent code.

Maximum string length: 8192

env_references

any[] | null

Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time

input_schema

object | null

JSON Schema from Zod input

llm_models

any[] | null

Acceptable provider/model pairs from guild.yaml models, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}]

output_schema

object | null

JSON Schema from Zod output

published_at

string<date-time> | null

publishing_started_at

string<date-time> | null

raw_tools

any[] | null

Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin).

runtime_environment_id

string<uuid> | null

sha

string | null

Git commit SHA (40-character hexadecimal). For agents: set on version creation. For integrations: set after code is stored in GitHub.

Maximum string length: 40

summary

string | null

Commit message summary. For agents: set on version creation. For integrations: set after code is stored in GitHub.

Maximum string length: 500

tools

any[] | null

version_number

string | null

The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version

Maximum string length: 100

agent

any

author

any

status

any

version_type

any

⌘I

Create an agent version

curl --request POST \
  --url https://api.guild.ai/v1/agents/{agent_id_or_name}/versions \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "skip_validation": false,
  "publish": false,
  "files": null,
  "bundle": null,
  "encoding": null,
  "commit_sha": null,
  "summary": null,
  "version_number": null
}
'

import requests

url = "https://api.guild.ai/v1/agents/{agent_id_or_name}/versions"

payload = {
    "skip_validation": False,
    "publish": False,
    "files": None,
    "bundle": None,
    "encoding": None,
    "commit_sha": None,
    "summary": None,
    "version_number": None
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    skip_validation: false,
    publish: false,
    files: null,
    bundle: null,
    encoding: null,
    commit_sha: null,
    summary: null,
    version_number: null
  })
};

fetch('https://api.guild.ai/v1/agents/{agent_id_or_name}/versions', 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.guild.ai/v1/agents/{agent_id_or_name}/versions",
  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([
    'skip_validation' => false,
    'publish' => false,
    'files' => null,
    'bundle' => null,
    'encoding' => null,
    'commit_sha' => null,
    'summary' => null,
    'version_number' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$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.guild.ai/v1/agents/{agent_id_or_name}/versions"

	payload := strings.NewReader("{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	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.guild.ai/v1/agents/{agent_id_or_name}/versions")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.guild.ai/v1/agents/{agent_id_or_name}/versions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"skip_validation\": false,\n  \"publish\": false,\n  \"files\": null,\n  \"bundle\": null,\n  \"encoding\": null,\n  \"commit_sha\": null,\n  \"summary\": null,\n  \"version_number\": null\n}"

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

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "author_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "validation_status": "SKIPPED",
  "dependencies": {},
  "description": "<string>",
  "env_references": [
    "<unknown>"
  ],
  "input_schema": {},
  "llm_models": [
    "<unknown>"
  ],
  "output_schema": {},
  "published_at": "2023-11-07T05:31:56Z",
  "publishing_started_at": "2023-11-07T05:31:56Z",
  "raw_tools": [
    "<unknown>"
  ],
  "runtime_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sha": "<string>",
  "summary": "<string>",
  "tools": [
    "<unknown>"
  ],
  "version_number": "<string>",
  "agent": "<unknown>",
  "author": "<unknown>",
  "status": "<unknown>",
  "version_type": "<unknown>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "author_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "validation_status": "SKIPPED",
  "dependencies": {},
  "description": "<string>",
  "env_references": [
    "<unknown>"
  ],
  "input_schema": {},
  "llm_models": [
    "<unknown>"
  ],
  "output_schema": {},
  "published_at": "2023-11-07T05:31:56Z",
  "publishing_started_at": "2023-11-07T05:31:56Z",
  "raw_tools": [
    "<unknown>"
  ],
  "runtime_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sha": "<string>",
  "summary": "<string>",
  "tools": [
    "<unknown>"
  ],
  "version_number": "<string>",
  "agent": "<unknown>",
  "author": "<unknown>",
  "status": "<unknown>",
  "version_type": "<unknown>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "<string>",
  "message": "<string>"
}

Get Started

OAuth

Workspaces

Triggers

Agents

Agent versions

Sessions

Skills

Integrations

Accounts

Organizations and users

Customer connectors

Create an agent version

Authorizations

Path Parameters

Body

Response