Agents API

Create, configure, and execute AI agents programmatically. All endpoints require authentication via API key or OAuth token.

Base path: /api/v1/agents

Endpoints

List Agents

GET /api/v1/agents

Returns all agents in the authenticated tenant. Supports pagination and filtering.

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Results per page (default: 20, max: 100)
appId	string	Filter by workspace
teamId	string	Filter by team
status	string	Filter by status: available, paused, registered

Response:

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Lead Qualifier",
      "role": "Sales Development",
      "model": "claude-sonnet-4-6",
      "status": "available",
      "teamId": "team_xyz",
      "appId": "app_456",
      "createdAt": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

Create Agent

POST /api/v1/agents

Field	Type	Required	Description
name	string	Yes	Agent display name
appId	string	Yes	Target workspace ID
role	string	No	Agent's organizational role
description	string	No	What the agent does
model	string	No	LLM model ID (default: claude-sonnet-4-6)
systemPrompt	string	No	Core behavior instructions
contextPrompt	string	No	Company/customer context

Response (201):

{
  "id": "agent_new123",
  "name": "Lead Qualifier",
  "role": "Sales Development",
  "model": "claude-sonnet-4-6",
  "status": "available",
  "appId": "app_456",
  "createdAt": "2026-04-12T14:30:00Z"
}

Get Agent

GET /api/v1/agents/:id

Returns full agent details including system prompt, tools, and configuration.

Update Agent

POST /api/v1/agents/:id

Update any agent field. Only provided fields are changed.

Field	Type	Description
name	string	Display name
role	string	Organizational role
model	string	LLM model ID
systemPrompt	string	Core instructions
contextPrompt	string	Company context
status	string	available or paused

Delete Agent

DELETE /api/v1/agents/:id

Permanently removes the agent. Conversations and audit logs are preserved.

Execute Agent

POST /api/v1/agents/:id/execute

Send a message and receive a response. The agent uses its full tool set, memory, and conversation context.

Field	Type	Required	Description
message	string	Yes	User message
conversationId	string	No	Resume existing conversation
enableTools	boolean	No	Allow tool use (default: true)
maxTokens	integer	No	Max response tokens
stream	boolean	No	Enable streaming (default: false)

Response:

{
  "output": "Based on the lead's profile, they match our ICP criteria...",
  "conversationId": "conv_789",
  "cost": 0.0034,
  "tokenUsage": {
    "inputTokens": 1250,
    "outputTokens": 340
  },
  "toolCalls": [
    {
      "name": "hubspot_search",
      "input": { "query": "company:Acme" },
      "result": { "contacts": 3 }
    }
  ],
  "duration": 2340
}

Chat (Streaming)

POST /api/v1/agents/:id/chat

Same as execute but always streams the response via Server-Sent Events.

Pause / Resume Agent

POST /api/v1/agents/:id/pause
POST /api/v1/agents/:id/resume

Paused agents reject new executions. Existing conversations are preserved.

Execution History

GET /api/v1/agents/:id/runs

Returns paginated execution history with cost, duration, and tool calls.

Parameter	Type	Description
page	integer	Page number
limit	integer	Results per page (max: 100)

Duplicate Agent

POST /api/v1/agents/:id/duplicate

Creates a copy of the agent with a new ID. System prompt, tools, and configuration are cloned.

Common Patterns

Create and Execute in One Flow

# 1. Create the agent
curl -X POST https://app.meetloyd.com/api/v1/agents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FAQ Assistant",
    "appId": "app_456",
    "model": "claude-sonnet-4-6",
    "systemPrompt": "You are a helpful FAQ assistant for Acme Corp."
  }'

# 2. Execute it
curl -X POST https://app.meetloyd.com/api/v1/agents/agent_new123/execute \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What is your return policy?" }'

Multi-Turn Conversation

Pass the conversationId from the first response to maintain context:

# First message
RESPONSE=$(curl -s -X POST .../agents/agent_123/execute \
  -d '{ "message": "Research Acme Corp" }')

CONV_ID=$(echo $RESPONSE | jq -r '.conversationId')

# Follow-up (same conversation)
curl -X POST .../agents/agent_123/execute \
  -d "{ \"message\": \"What about their competitors?\", \"conversationId\": \"$CONV_ID\" }"

---

💬

Conversations API

Manage conversation lifecycle and messages

📋

Tasks API

Create and execute scheduled tasks

🔑

Authentication

API keys, OAuth, and scopes