Create an agent

POST

agents

Create an agent

curl --request POST \
  --url https://api.guild.ai/v1/agents \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": null,
  "is_public": false,
  "avatar_url": null,
  "owner_id": null,
  "maintainer_id": null,
  "category": null,
  "tags": null,
  "forked_from_version": null,
  "template": null
}
'

import requests

url = "https://api.guild.ai/v1/agents"

payload = {
    "name": "<string>",
    "description": None,
    "is_public": False,
    "avatar_url": None,
    "owner_id": None,
    "maintainer_id": None,
    "category": None,
    "tags": None,
    "forked_from_version": None,
    "template": 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({
    name: '<string>',
    description: null,
    is_public: false,
    avatar_url: null,
    owner_id: null,
    maintainer_id: null,
    category: null,
    tags: null,
    forked_from_version: null,
    template: null
  })
};

fetch('https://api.guild.ai/v1/agents', 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",
  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([
    'name' => '<string>',
    'description' => null,
    'is_public' => false,
    'avatar_url' => null,
    'owner_id' => null,
    'maintainer_id' => null,
    'category' => null,
    'tags' => null,
    'forked_from_version' => null,
    'template' => 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"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": 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")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.guild.ai/v1/agents")

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  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": null\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_type": "GUILD_TYPESCRIPT",
  "description": "<string>",
  "is_public": true,
  "name": "<string>",
  "owner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cached_forks_count": 123,
  "cached_installs_count": 123,
  "cached_likes_count": 123,
  "is_pinned": true,
  "moderation_state": "ACTIVE",
  "status": "CREATED",
  "archived_at": "2023-11-07T05:31:56Z",
  "archived_by_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "avatar_url": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "creation_template": "LLM",
  "forked_from_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "generated_description": "<string>",
  "maintainer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "archived_by": "<unknown>",
  "category": "<unknown>",
  "forks_count": 123,
  "full_name": "<string>",
  "git_url": "<string>",
  "installs_count": 123,
  "is_description_autogenerated": "<unknown>",
  "latest_published_version": "<unknown>",
  "latest_version": "<unknown>",
  "likes_count": 123,
  "maintainer": {},
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "creator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "cached_forks_count": 123,
    "cached_forks_public_count": 123,
    "cached_installs_count": 123,
    "cached_installs_public_count": 123,
    "cached_likes_count": 123,
    "cached_likes_public_count": 123,
    "avatar_url": "<string>",
    "banner_url": "<string>",
    "bio": "<string>",
    "discord_url": "<string>",
    "email_domain": "<string>",
    "full_name": "<string>",
    "github_url": "<string>",
    "linkedin_url": "<string>",
    "threads_url": "<string>",
    "website_url": "<string>",
    "x_url": "<string>",
    "youtube_url": "<string>",
    "member_count": "<unknown>",
    "viewer_membership_id": "<unknown>",
    "viewer_membership_public": "<unknown>",
    "viewer_role": "ADMIN",
    "type": "organization"
  },
  "public_profile_url": "<unknown>",
  "type": "<unknown>",
  "viewer_can_edit": true
}

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

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

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

Authorizations

Authorization

string

header

required

Account API key: key id as the username, secret as the password.

Body

application/json

name

string

required

description

string | null

is_public

boolean

default:false

avatar_url

string | null

owner_id

string<uuid> | null

maintainer_id

string<uuid> | null

Response

Successful response

string<uuid>

created_at

string<date-time>

updated_at

string<date-time>

agent_type

enum<string>

Available options:

GUILD_TYPESCRIPT,

GUILD_NATIVE,

GOOSE,

OPENCLAW,

LANGGRAPH

description

string

Manual description field. Can be empty; the effective description falls back to generated_description.

is_public

boolean

Whether the asset is visible to the community or only its owner.

name

string

Unique name identifying the asset within the owner account.

Maximum string length: 100

owner_id

string<uuid>

The account that owns this entity.

cached_forks_count

integer

A cached version of the forks count. Might not be up to date.

cached_installs_count

integer

A cached version of the installs count. Might not be up to date.

cached_likes_count

integer

A cached version of the likes count. Might not be up to date.

is_pinned

boolean

If true, it means the agent is pinned on the owner's account's profile.

moderation_state

enum<string>

Operator-controlled moderation/curation state. Owners cannot change this; only operators can, via the hub kebab menu or ops tooling.

Available options:

ACTIVE,

DEMOTED,

UNLISTED,

DISABLED,

TAKEN_DOWN

status

enum<string>

Available options:

CREATED,

GIT_REPOSITORY_CREATED,

READY

archived_at

string<date-time> | null

archived_by_id

string<uuid> | null

avatar_url

string | null

Maximum string length: 255

category_id

string<uuid> | null

The category this agent is sorted in.

creation_template

enum<string> | null

If applicable, the template that was selected during the creation of this agent. Note: it doesn't mean the agent is still following the template now.

Available options:

LLM,

AUTO_MANAGED_STATE,

BLANK,

GOOSE,

GUILD_NATIVE,

OPENCLAW,

LANGGRAPH

forked_from_id

string<uuid> | null

If applicable, the ID of the agent version this agent was forked from.

generated_description

string | null

LLM-generated description based on agent code. Regenerated automatically on every commit.

maintainer_id

string<uuid> | null

OPTIONAL. Refers to the person within an organization that is tasked with maintaining the agent.

archived_by

any

category

any

forks_count

integer

Number of times this agent has been forked

full_name

string

Full agent name in format "owner_name/agent_name"

git_url

string

URL to the agent's git repository

installs_count

integer

Number of times this agent has been installed in workspaces

is_description_autogenerated

any

latest_published_version

any

latest_version

any

likes_count

integer

Number of likes this agent has received

maintainer

object | null

Maintainer of the agent (for organization-owned agents)

owner

object

Option 1
Option 2

Show child attributes

public_profile_url

any

type

any

viewer_can_edit

boolean

Whether the current viewer can edit this agent

⌘I

Create an agent

curl --request POST \
  --url https://api.guild.ai/v1/agents \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "description": null,
  "is_public": false,
  "avatar_url": null,
  "owner_id": null,
  "maintainer_id": null,
  "category": null,
  "tags": null,
  "forked_from_version": null,
  "template": null
}
'

import requests

url = "https://api.guild.ai/v1/agents"

payload = {
    "name": "<string>",
    "description": None,
    "is_public": False,
    "avatar_url": None,
    "owner_id": None,
    "maintainer_id": None,
    "category": None,
    "tags": None,
    "forked_from_version": None,
    "template": 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({
    name: '<string>',
    description: null,
    is_public: false,
    avatar_url: null,
    owner_id: null,
    maintainer_id: null,
    category: null,
    tags: null,
    forked_from_version: null,
    template: null
  })
};

fetch('https://api.guild.ai/v1/agents', 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",
  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([
    'name' => '<string>',
    'description' => null,
    'is_public' => false,
    'avatar_url' => null,
    'owner_id' => null,
    'maintainer_id' => null,
    'category' => null,
    'tags' => null,
    'forked_from_version' => null,
    'template' => 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"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": 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")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.guild.ai/v1/agents")

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  \"name\": \"<string>\",\n  \"description\": null,\n  \"is_public\": false,\n  \"avatar_url\": null,\n  \"owner_id\": null,\n  \"maintainer_id\": null,\n  \"category\": null,\n  \"tags\": null,\n  \"forked_from_version\": null,\n  \"template\": null\n}"

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "agent_type": "GUILD_TYPESCRIPT",
  "description": "<string>",
  "is_public": true,
  "name": "<string>",
  "owner_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cached_forks_count": 123,
  "cached_installs_count": 123,
  "cached_likes_count": 123,
  "is_pinned": true,
  "moderation_state": "ACTIVE",
  "status": "CREATED",
  "archived_at": "2023-11-07T05:31:56Z",
  "archived_by_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "avatar_url": "<string>",
  "category_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "creation_template": "LLM",
  "forked_from_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "generated_description": "<string>",
  "maintainer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "archived_by": "<unknown>",
  "category": "<unknown>",
  "forks_count": 123,
  "full_name": "<string>",
  "git_url": "<string>",
  "installs_count": 123,
  "is_description_autogenerated": "<unknown>",
  "latest_published_version": "<unknown>",
  "latest_version": "<unknown>",
  "likes_count": 123,
  "maintainer": {},
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "creator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "cached_forks_count": 123,
    "cached_forks_public_count": 123,
    "cached_installs_count": 123,
    "cached_installs_public_count": 123,
    "cached_likes_count": 123,
    "cached_likes_public_count": 123,
    "avatar_url": "<string>",
    "banner_url": "<string>",
    "bio": "<string>",
    "discord_url": "<string>",
    "email_domain": "<string>",
    "full_name": "<string>",
    "github_url": "<string>",
    "linkedin_url": "<string>",
    "threads_url": "<string>",
    "website_url": "<string>",
    "x_url": "<string>",
    "youtube_url": "<string>",
    "member_count": "<unknown>",
    "viewer_membership_id": "<unknown>",
    "viewer_membership_public": "<unknown>",
    "viewer_role": "ADMIN",
    "type": "organization"
  },
  "public_profile_url": "<unknown>",
  "type": "<unknown>",
  "viewer_can_edit": true
}

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

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

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

Get Started

Workspaces

Agents

Sessions

Skills

Accounts

Create an agent

Authorizations

Body

Response