List agents

curl --request GET \
  --url https://www.asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.asteragents.com/api/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://www.asteragents.com/api/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.asteragents.com/api/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.asteragents.com/api/agents")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

[
  {
    "id": 1,
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries",
    "logoUrl": null,
    "conversationStarters": [
      "How can I help you today?",
      "What issue are you experiencing?"
    ],
    "model": "openai:gpt-4o",
    "maxToolRoundtrips": 50,
    "systemPrompt": "You are a helpful customer support agent...",
    "tools": {},
    "mcpServers": null,
    "stage": "released",
    "showInChat": true,
    "emailSlug": "support-bot",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:00:00.000Z",
    "tags": [
      {
        "id": 1,
        "name": "Production"
      }
    ]
  }
]

{
  "error": "User is not part of any organization"
}

{
  "error": "Internal Server Error"
}

GET

agents

List agents

curl --request GET \
  --url https://www.asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://www.asteragents.com/api/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://www.asteragents.com/api/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://www.asteragents.com/api/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://www.asteragents.com/api/agents")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

[
  {
    "id": 1,
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries",
    "logoUrl": null,
    "conversationStarters": [
      "How can I help you today?",
      "What issue are you experiencing?"
    ],
    "model": "openai:gpt-4o",
    "maxToolRoundtrips": 50,
    "systemPrompt": "You are a helpful customer support agent...",
    "tools": {},
    "mcpServers": null,
    "stage": "released",
    "showInChat": true,
    "emailSlug": "support-bot",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:00:00.000Z",
    "tags": [
      {
        "id": 1,
        "name": "Production"
      }
    ]
  }
]

{
  "error": "User is not part of any organization"
}

{
  "error": "Internal Server Error"
}

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Response

Successfully retrieved agents

integer

required

Unique agent identifier

Example:

1

name

string

required

Agent name

Example:

"Customer Support Agent"

stage

enum<string>

required

Agent lifecycle stage

Available options:

development,

released

Example:

"development"

showInChat

boolean

required

Whether the agent appears in the chat interface

Example:

true

createdAt

string<date-time>

required

When the agent was created

Example:

"2024-01-15T10:30:00.000Z"

updatedAt

string<date-time>

required

When the agent was last updated

Example:

"2024-01-20T14:00:00.000Z"

description

string | null

Short description of the agent's purpose

Example:

"Handles customer inquiries and support tickets"

logoUrl

string | null

URL to the agent's logo image

conversationStarters

string[] | null

Suggested conversation starters shown to users

Example:

[
  "How can I help you today?",
  "What issue are you experiencing?"
]

model

string | null

Model identifier (e.g., openai:gpt-4o)

Example:

"openai:gpt-4o"

maxToolRoundtrips

integer | null

Maximum number of tool call roundtrips per response

Example:

50

systemPrompt

string | null

System prompt / instructions for the agent

tools

object | null

Tool definitions keyed by tool name

mcpServers

integer[] | null

Connected MCP server IDs (integer mcp_server.id values)

emailSlug

string | null

Custom email slug for the agent's email address

Example:

"support-bot"

publishedVersionId

integer | null

ID of the agent_version snapshot this agent's config currently reflects. Every save appends a version and advances this pointer; see GET /agents/versions. The live agent fields above remain the source of truth — this is bookkeeping for history and rollback.

Example:

42

API Documentation

Admin API

Files API

Agents API

Tools API

Agent Tags API

Knowledge Bases API

Skills API

Conversations API

Scheduled Tasks API

Other Endpoints

Legacy Endpoints (Deprecated)

List agents

Authorizations

Response