Skip to main content
GET
/
agents
List agents
curl --request GET \
  --url https://asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>'
[
  {
    "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"
      }
    ]
  }
]

Authorizations

​
Authorization
string
header
required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Response

Successfully retrieved agents

​
id
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

Tool definitions keyed by tool name

​
mcpServers
string[] | null

Connected MCP server IDs

​
emailSlug
string | null

Custom email slug for the agent's email address

Example:

"support-bot"

​
tags
object[]

Tags associated with this agent