API Documentation

The AgentWorks API allows you to programmatically manage agents, conversations, contacts, and more. Available on Pro, Business, and Enterprise plans.

Base URL

https://api.agentworksstudio.com/v1

Auth

Bearer token (API key)

Format

JSON request/response

Rate Limits: 100 requests/second (Team), 1000 requests/second (Enterprise). Rate limit headers included in all responses.

Authentication

All API requests require a Bearer token. Generate your API key from the Settings → API Keys section of your dashboard.

Authentication Header
bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agentworksstudio.com/v1/agents

API Key Scopes

agents:readList and view agents
agents:writeCreate, update, and delete agents
conversations:readView conversation history
conversations:writeSend messages to conversations
contacts:readList and view contacts
contacts:writeCreate and update contacts
webhooks:manageConfigure webhook endpoints
adminFull access to all resources

Agents API

Manage your AI agents — list, create, update configuration, and monitor status.

Conversations API

Access conversation history and send messages to active conversations.

Webhooks

Receive real-time notifications when events happen in your AgentWorks workspace.

Available Events

conversation.startedNew conversation created
conversation.messageNew message in conversation
conversation.endedConversation closed
agent.escalationAgent escalated to human
contact.createdNew contact added to CRM
contact.updatedContact information updated
task.completedAgent completed a task
agent.errorAgent encountered an error
Webhook Payload Example
json
{
  "event": "conversation.message",
  "timestamp": "2026-02-18T16:30:00Z",
  "data": {
    "conversation_id": "conv_xyz789",
    "agent_id": "agt_abc123",
    "message": {
      "id": "msg_456",
      "content": "I'd be happy to schedule a showing for you!",
      "sender": "agent",
      "channel": "sms"
    },
    "contact": {
      "id": "cnt_789",
      "name": "John Smith",
      "email": "john@example.com"
    }
  },
  "signature": "sha256=..."
}
Security: All webhook payloads include an HMAC-SHA256 signature in the X-AgentWorks-Signature header. Verify this signature using your webhook secret to ensure payload authenticity.

Company Discovery

Your industry ambassador does the onboarding for your prospect. A visitor chats with the ambassador (e.g. Jackie for construction) and gives just a name and website URL. The agent then crawls the site, drills the menu, and extracts a complete company & contact profile — name, phone, address, hours, social links, company history, and products/services — to auto-fill the CRM without asking a single onboarding question. That discovery becomes a formal Assessment (PDF, emailed to confirm), and the prospect gets a ready-made “taste” workspace they can log into and start training their own agent before they ever pay.

The pipeline

The whole journey runs on the Deal Pipeline — each stage automatically triggers the next, and agents advance the deal toward closed/won.

1
Discovery — Crawl the prospect’s site → auto-fill CRM company + contact profile.
2
Assessment — Generate an assessment PDF from the discovery and email it to confirm.
3
Taste tenant — Provision a free workspace and email a login link — they start training immediately.
4
Quote — A follow-up agent drafts an MSP services quote from the assessment.
5
Sign + deposit — Client accepts all/parts of the quote, signs a 12-month agreement, pays the setup deposit — the deal closes.
6
Onboarding — Moves to Prism onboarding: Projects → Tasks → Beacons on a schedule, with human-in-the-loop checkpoints.
7
Go Live — The project completes and the client goes live.

What gets captured

Company name & industry
Phone & email
Address & hours
Social links
Company history
Products & services
Primary contact (name, title)
Confidence score & sources
How to trigger it: just tell the ambassador your name and your website (e.g. “I’m Joe, my site is qualitycountsconstructionllc.com”). Discovery runs in the background — the ambassador keeps chatting and you get your assessment by email, plus a link to your free workspace.

Code Examples

Quick-start examples in cURL, Node.js, and Python.

List Agents

cURL
bash
curl -X GET "https://api.agentworksstudio.com/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Node.js
javascript
const response = await fetch(
  'https://api.agentworksstudio.com/v1/agents',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  }
);

const { agents } = await response.json();
console.log(`Found ${agents.length} agents`);
Python
python
import requests

response = requests.get(
    'https://api.agentworksstudio.com/v1/agents',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    }
)

agents = response.json()['agents']
print(f"Found {len(agents)} agents")

Send a Message

Node.js — Send message to conversation
javascript
const response = await fetch(
  'https://api.agentworksstudio.com/v1/conversations/conv_xyz789/messages',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      content: 'Hi! I noticed you were looking at properties in Downtown.',
      sender: 'human',
    }),
  }
);

const message = await response.json();
console.log('Message sent:', message.id);

Webhook Handler

Node.js — Express webhook handler
javascript
import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhooks/agentworks', (req, res) => {
  // Verify signature
  const signature = req.headers['x-agentworks-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Handle event
  const { event, data } = req.body;

  switch (event) {
    case 'conversation.message':
      console.log('New message:', data.message.content);
      break;
    case 'agent.escalation':
      console.log('Escalation needed:', data.reason);
      // Notify team via Slack, email, etc.
      break;
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Ready to integrate?

API access is available on every AI Front Desk plan (from $397/mo, no setup fee) and Enterprise.

Get Team Plan Contact Sales