---
title: "Tools Reference — AVCodex Docs"
description: "Tools Reference — AVCodex documentation for AV integrators, programmers, and ops teams."
lang: en
json-ld:
---

[](/)

Solutions

[Pricing](/pricing)[The Signal](/blog)[Resources](/resources)

Learn

[Free AI Assessment](/scorecard)[Get Started →](/pricing)

[Documentation Home](/docs)

Guides 

Getting Started

-   [The Alchemist Copilot](/docs/guides/the-alchemist-copilot)
-   [Choosing a Model](/docs/guides/choosing-a-model)
-   [Skills & Templates](/docs/guides/skills-and-templates)
-   [Pricing & Usage](/docs/guides/pricing-and-usage)
-   [Understanding Tokens](/docs/guides/understanding-tokens)
-   [Maximize AVCodex Capabilities](/docs/guides/maximize-avcodex-capabilities)

Knowledge & Memory

-   [How Knowledge Sources Work](/docs/guides/how-knowledge-sources-work)
-   [Knowledge Retrieval Settings](/docs/guides/knowledge-retrieval-settings)
-   [User Memory](/docs/guides/user-memory)
-   [Consumer Brain](/docs/guides/consumer-brain)

Agent Capabilities

-   [Image Recognition](/docs/guides/image-recognition)
-   [Image Generation](/docs/guides/image-generation)
-   [Video Generation](/docs/guides/video-generation)
-   [Deep Research and Deep Thinking](/docs/guides/deep-research-and-deep-thinking)
-   [Heartbeat (Proactive AI Outreach)](/docs/guides/heartbeat-proactive-ai-outreach)
-   [Database Connections](/docs/guides/database-connections)
-   [Agent-to-Agent Links](/docs/guides/agent-to-agent-links)
-   [Message Tagging](/docs/guides/message-tagging)
-   [Lead Generation Forms](/docs/guides/lead-generation-forms)
-   [Multilingual Apps](/docs/guides/multilingual-apps)
-   [Understanding Evaluations](/docs/guides/understanding-evaluations)

Design & Experience

-   [Style Studio](/docs/guides/style-studio)
-   [Component Studio](/docs/guides/component-studio)
-   [HQ Profile](/docs/guides/hq-profile)
-   [Multiplayer Chat](/docs/guides/multiplayer-chat)
-   [Circles](/docs/guides/circles)
-   [Desktop Agent](/docs/guides/desktop-agent)

Voice & Phone

-   [Phone Numbers](/docs/guides/phone-numbers)
-   [Outbound Calling](/docs/guides/outbound-calling)
-   [Voice Cloning](/docs/guides/voice-cloning)

Publish & Share

-   [Embed Chat Widget](/docs/guides/embed-chat-widget)
-   [Custom Domains](/docs/guides/custom-domains)
-   [PWA Installation](/docs/guides/pwa-installation)
-   [AVCodex Sites](/docs/guides/avcodex-sites)
-   [Embed on Kajabi](/docs/guides/embed-on-kajabi)
-   [How to Use AVCodex with Claude Code](/docs/guides/how-to-use-avcodex-with-claude-code)

Monetization & Access

-   [Selling Access](/docs/guides/selling-access)
-   [Consumer Monetization](/docs/guides/consumer-monetization)
-   [Access Control](/docs/guides/access-control)
-   [Bring Your Own Auth](/docs/guides/bring-your-own-auth)
-   [Clever SSO for Schools](/docs/guides/clever-sso-for-schools)

Analytics & Operations

-   [Analytics & Chat History](/docs/guides/analytics-and-chat-history)
-   [Performance Dashboard](/docs/guides/performance-dashboard)
-   [Programmatic Usage Stats](/docs/guides/programmatic-usage-stats)
-   [Session Lifecycle Webhooks](/docs/guides/session-lifecycle-webhooks)
-   [Audit Logs](/docs/guides/audit-logs)

Teams & White-Label

-   [Team Management](/docs/guides/team-management)
-   [Enterprise Whitelabel](/docs/guides/enterprise-whitelabel)

Alchemist Platform

-   [Alchemist Tickets](/docs/guides/alchemist-tickets)
-   [Alchemist Getting Started](/docs/guides/alchemist-getting-started)
-   [Alchemist Working with Tickets](/docs/guides/alchemist-working-with-tickets)
-   [Alchemist Local Development](/docs/guides/alchemist-local-development)

Alchemist Operations

-   [Alchemist Environment Variables](/docs/guides/alchemist-environment-variables)
-   [Alchemist Deploys and Domains](/docs/guides/alchemist-deploys-and-domains)
-   [Alchemist Self-Healing](/docs/guides/alchemist-self-healing)

Alchemist API & Automation

-   [Alchemist API Keys](/docs/guides/alchemist-api-keys)
-   [Alchemist MCP Server](/docs/guides/alchemist-mcp-server)
-   [Alchemist Pipeline Configuration](/docs/guides/alchemist-pipeline-configuration)
-   [Alchemist Pipeline Permutations](/docs/guides/alchemist-pipeline-permutations)

Developer Platform

-   [Building Custom MCP Servers](/docs/guides/building-custom-mcp-servers)
-   [Consumer OAuth for Custom MCP Servers](/docs/guides/consumer-oauth-for-custom-mcp-servers)

AVCodex MCP Server

-   [Overview](/docs/guides/overview)
-   [MCP Reference](/docs/guides/mcp-reference)
-   [Setup & Installation](/docs/guides/setup-and-installation)
-   [Authentication](/docs/guides/authentication)
-   [Tools Reference](/docs/guides/tools-reference)
-   [Common Workflows](/docs/guides/common-workflows)
-   [Rate Limits](/docs/guides/rate-limits)

Custom Actions 

Pro Actions 

API 

Builder API 

Agentic Commerce (ACP) 

Integrations 

[Docs](/docs)/ Guides / AVCodex MCP Server 

# Tools Reference

Last updated · MAR 2026 · [Read as Markdown](/docs/guides/tools-reference.md)

This guide documents the tools available in the AVCodex MCP Server, organized by category.

## [Quick reference# ](#quick-reference)

Jump to a category or use this table to find tools quickly:

Category

Tools

Description

[Apps](#apps)

13

Create, publish, duplicate, rollback, and deploy agents

[Config](#configuration)

9

System prompts, models, settings, branding, suggestions

[Knowledge](#knowledge-sources)

13

Add URLs, documents, text, link sources, crawl monitoring

[Analytics](#analytics)

14

Usage data, conversations, metrics, search, moderation

[Tags](#tags)

8

Intent tagging, classification, utterance generation

[Evals](#evaluations)

8

Quality testing and evaluation

[Custom Actions](#custom-actions)

6

API integrations and testing

[MCP Integrations](#mcp-integrations)

6

External MCP servers and hosted integrations

[Deployments](#deployments)

10

Slack, WhatsApp, Discord, GitHub, Email, Voice

[Consumers](#consumers)

4

End-user management and memory

[Workspaces](#workspaces)

4

Workspace management

[Billing](#billing)

5

Subscription, credits, usage, capabilities

[Prompt Engineering](#prompt-engineering)

5

AI-assisted prompt improvement and suggestions

[Action Collections](#action-collections)

10

Reusable action bundles with sharing

[Variables](#variables)

5

Application config variables

[Heartbeat](#heartbeat)

3

Proactive messaging configuration and history

[Agent Links](#agent-links)

4

Agent-to-agent delegation

[Database Connections](#database-connections)

5

External database connections

[Monetization](#monetization)

5

Consumer credit packages

> **Note:** AVCodex agents are stored as "apps" in the underlying API. Tool names and parameters use `app` and `app_id`. They map to AVCodex agents.

* * *

## [Apps# ](#apps)

Core CRUD operations for managing AVCodex agents.

### [list\_apps# ](#list-apps)

List every agent accessible to the authenticated user.

**Scope:** `apps:read`

Parameter

Type

Required

Description

workspace\_id

string

No

Filter to a specific workspace

limit

number

No

Max results (1-100, default 20)

offset

number

No

Pagination offset

**Example:**

code 

```
"List all my AVCodex agents"
"Show agents in workspace 42"
```

* * *

### [get\_app# ](#get-app)

Get detailed information about a specific agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Example:**

code 

```
"Get details for agent 123"
"Show me the configuration of my Crestron support agent"
```

* * *

### [create\_app# ](#create-app)

Create a new agent in a workspace.

**Scope:** `apps:write`

Parameter

Type

Required

Description

name

string

Yes

Agent name (1-100 chars)

workspace\_id

string

Yes

Workspace to create in

description

string

No

Agent description (max 2000 chars)

system\_prompt

string

No

Initial system prompt. Server accepts up to 2M chars; the builder UI cap is derived per-model from the context window (~50% of the window at 4 chars/token).

model\_id

string

No

Model ID (default: GPT\_4\_1)

**Example:**

code 

```
"Create a Crestron tier-1 support agent called RoomMedic in workspace 5"
"Make a new agent named RFP Responder with a helpful estimating prompt"
```

* * *

### [update\_app# ](#update-app)

Update an existing agent's properties.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

No

New name

description

string

No

New description

is\_public

boolean

No

Make agent publicly listed

**Example:**

code 

```
"Rename agent 123 to 'Tier-1 Support v2'"
"Make my client-facing AV agent publicly listed"
```

* * *

### [delete\_app# ](#delete-app)

Soft-delete an agent.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Example:**

code 

```
"Delete agent 123"
"Remove the test agent I created"
```

* * *

### [chat\_with\_app# ](#chat-with-app)

Send a message to an agent and get a response. Useful for testing.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

message

string

Yes

Message to send

session\_id

string

No

Continue an existing session

> **Tip:** Use this tool to test agents after making changes. It is faster than switching to the web UI.

**Example:**

code 

```
"Test my Crestron agent with the question 'What does Cresnet error 87 mean?'"
"Send 'hello' to agent 123 to check if it's working"
```

* * *

### [search\_apps# ](#search-apps)

Search agents by name or description within your organization.

**Scope:** `apps:read`

Parameter

Type

Required

Description

query

string

Yes

Search query to match against agent names and descriptions

limit

number

No

Max results (default 10)

* * *

### [publish\_app# ](#publish-app)

Publish the current agent configuration to make it live for consumers. Creates a version snapshot and deploys it.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

tag

string

No

Version tag/label (e.g. `v2.0`, `bugfix`)

**Returns:** `version_id`, `already_published` flag, and the tag used.

* * *

### [list\_app\_versions# ](#list-app-versions)

List published version history for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

limit

number

No

Max results (default 20)

* * *

### [duplicate\_app# ](#duplicate-app)

Create a copy of an existing agent with all its configuration, system prompt, and settings. Useful for spinning up a per-client agent from a template (one base "Crestron Tier-1" agent cloned for every managed-services client).

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID to duplicate

name

string

No

Name for the copy (default: `Original Name (Copy)`)

workspace\_id

string

No

Target workspace (defaults to same workspace)

* * *

### [restore\_app\_version# ](#restore-app-version)

Restore an agent's configuration to a previous version. Does not publish. Use `publish_app` afterward if needed.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

version\_id

string

Yes

Version ID to restore (from `list_app_versions`)

* * *

### [rollback\_app\_version# ](#rollback-app-version)

Rollback an agent to a previously published version and immediately publish it. Combines restore and publish in one step.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

version\_id

string

Yes

Version ID to rollback to (must be a previously launched version)

* * *

### [get\_app\_url# ](#get-app-url)

Get the consumer-facing URL for an agent (custom domain, vanity subdomain, or default path). Also returns the embed widget snippet.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** `consumer_url`, `default_url`, `has_custom_domain`, and `embed_snippet`.

* * *

## [Configuration# ](#configuration)

Manage agent settings, system prompts, and branding.

### [get\_system\_prompt# ](#get-system-prompt)

Get the system prompt for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_system\_prompt# ](#update-system-prompt)

Update an agent's system prompt.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

system\_prompt

string

Yes

New system prompt text

> **Warning:** Changes take effect immediately for new conversations. Use `chat_with_app` to test before deploying to users.

* * *

### [get\_model# ](#get-model)

Get the AI model configuration for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_model# ](#update-model)

Change the AI model for an agent.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

model

string

Yes

Model ID (e.g., GPT\_4\_1, CLAUDE\_3\_5\_SONNET)

* * *

### [get\_settings# ](#get-settings)

Get detailed settings including RAG configuration.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_settings# ](#update-settings)

Update agent settings, capabilities, welcome messages, and suggested starters.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

settings

object

No

Settings JSONB (auth, chat options, etc.)

capabilities

object

No

Capabilities JSONB (features to enable/disable)

welcome\_messages

string\[\]

No

Welcome message rotation

suggested\_messages

string\[\]

No

Conversation starter suggestions shown to users

* * *

### [update\_branding# ](#update-branding)

Update visual branding for the agent.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

primary\_color

string

No

Hex color code (e.g. `#3B82F6`)

logo\_url

string

No

URL to logo image (light mode)

logo\_url\_dark

string

No

URL to logo image (dark mode)

input\_text\_hint

string

No

Placeholder text for the chat input

disclaimer\_text

string

No

Disclaimer shown below the chat

* * *

### [list\_suggestions# ](#list-suggestions)

Get the suggested conversation starters shown to users on the chat interface.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_suggestions# ](#update-suggestions)

Set the suggested conversation starters shown to users. Pass an empty array to clear all suggestions.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

suggestions

string\[\]

Yes

Array of suggestion strings (max 6 recommended)

**Example:**

code 

```
"Set the starter prompts for my support agent to: 'TSW touch panel is unresponsive', 'Cresnet device offline', 'Schedule a service call'"
```

* * *

## [Knowledge Sources# ](#knowledge-sources)

Manage RAG (Retrieval-Augmented Generation) knowledge bases. Load Crestron module reference, Biamp Tesira spec PDFs, AS-built drawings, AMX programming guides, internal commissioning SOPs.

### [list\_knowledge\_sources# ](#list-knowledge-sources)

List all knowledge sources for an agent.

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

status

string

No

Filter by status: `pending`, `processing`, `completed`, `failed`

type

string

No

Filter by type: `url`, `file`, `text`, `youtube`, `youtube_channel`, `sitemap`, `confluence`

limit

number

No

Max results (default 50)

offset

number

No

Pagination offset

* * *

### [get\_knowledge\_source# ](#get-knowledge-source)

Get details about a specific knowledge source.

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID

* * *

### [add\_url\_source# ](#add-url-source)

Add a URL as a knowledge source. Automatically detects YouTube, Instagram, TikTok, and regular web pages.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

url

string

Yes

URL to crawl

max\_depth

number

No

How many levels deep to crawl links (default 1)

crawl\_links

boolean

No

Whether to follow links on the page

max\_pages

number

No

Maximum number of pages to crawl

name

string

No

Custom name for the source

> **Note:** Smart Detection. YouTube URLs extract transcripts, social media extracts content, regular URLs are crawled. Useful for ingesting manufacturer training videos and a vendor's full doc site in one step.

**Example:**

code 

```
"Add https://docs.biamp.com/tesira to my design agent and crawl 3 levels deep"
"Add this Crestron training video to my onboarding agent's knowledge base"
```

* * *

### [add\_text\_source# ](#add-text-source)

Add raw text content as a knowledge source.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

content

string

Yes

Text content to add

name

string

Yes

Name for the source

**Example:**

code 

```
"Add this commissioning checklist text to my deployment agent's knowledge base"
```

* * *

### [delete\_knowledge\_source# ](#delete-knowledge-source)

Remove a knowledge source from an agent.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID

* * *

### [refresh\_knowledge\_source# ](#refresh-knowledge-source)

Re-crawl or re-process a knowledge source to update its content. Useful when a manufacturer publishes a new firmware-release notes page.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID

* * *

### [list\_active\_crawls# ](#list-active-crawls)

List knowledge sources currently being processed or queued for an agent.

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** Active processing jobs with job type, status, attempt counts, and the source name/URL being processed.

* * *

### [cancel\_crawl# ](#cancel-crawl)

Cancel all pending and in-progress processing jobs for a knowledge source.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID to cancel

The source status is set to `failed`. Jobs already running on a worker may complete, but no new queued jobs will start.

* * *

### [add\_document\_source# ](#add-document-source)

Upload one or more document files as knowledge sources. Files are provided as base64-encoded content. Drop in PDFs of Crestron module reference, Biamp DSP guides, Q-SYS Designer help exports, room CAD packages, AS-built docs.

**Scope:** `knowledge:write`

Supported formats: PDF, DOCX, TXT, MD, CSV, JSON, XLSX, XLS, and audio files (MP3, WAV, M4A, etc.).

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

files

object\[\]

Yes

Array of files (1 to 20)

Each file object requires `fileName` (with extension) and `content` (base64-encoded).

* * *

### [get\_crawl\_progress# ](#get-crawl-progress)

Get the processing progress for a knowledge source. Current status, chunk count, pages completed, and any error messages.

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID

* * *

### [link\_knowledge\_source# ](#link-knowledge-source)

Link a knowledge source from one agent to another, sharing its RAG data without duplicating it. Useful for sharing one master Crestron docs source across every client-specific support agent.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID to link

target\_app\_id

string

Yes

Agent ID to link the source to

* * *

### [unlink\_knowledge\_source# ](#unlink-knowledge-source)

Remove a linked knowledge source from an agent. Does not delete the original source.

**Scope:** `knowledge:write`

Parameter

Type

Required

Description

source\_id

string

Yes

Knowledge source ID

app\_id

string

Yes

Agent ID to unlink from

* * *

### [list\_linked\_knowledge\_sources# ](#list-linked-knowledge-sources)

List knowledge sources linked to an agent from other agents (shared sources).

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

## [Analytics# ](#analytics)

Access usage data, conversations, and metrics.

### [get\_app\_analytics# ](#get-app-analytics)

Get summary analytics for an agent: total sessions, messages, unique users, and date range stats.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

**Returns:** Total sessions, messages, unique users, first and last session timestamps.

* * *

### [search\_conversations# ](#search-conversations)

Search conversations with filters.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

query

string

No

Text to search for in messages

since

string

No

ISO date to filter from

limit

number

No

Max results (default 20)

offset

number

No

Pagination offset (default 0)

**Example:**

code 

```
"Find conversations about Cresnet timeouts in my support agent"
"Show recent conversations from the last week"
```

* * *

### [get\_conversation# ](#get-conversation)

Get a specific conversation with all messages.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

session\_id

string

Yes

Session ID

* * *

### [get\_top\_queries# ](#get-top-queries)

Get the most common user queries.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

limit

number

No

Number of queries (default 20)

since

string

No

ISO date to filter from (defaults to last 30 days)

* * *

### [get\_model\_usage# ](#get-model-usage)

Get LLM model usage breakdown (token counts by model) for an agent.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

* * *

### [get\_response\_time\_analytics# ](#get-response-time-analytics)

Get response time statistics based on message timestamps.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 7 days)

**Returns:** Total responses, avg response ms, p50, p95.

* * *

### [get\_user\_engagement# ](#get-user-engagement)

Get user engagement metrics: sessions per user, messages per session, return rate.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

* * *

### [search\_messages# ](#search-messages)

Search for specific text within messages across all conversations in an agent.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

query

string

Yes

Text to search for

role

string

No

Filter by role: `user`, `assistant`, or `system`

since

string

No

ISO date to filter from

limit

number

No

Max results (default 50, max 200)

offset

number

No

Pagination offset (default 0)

Returns matching messages with a 500-character content preview and session context.

* * *

### [search\_documentation# ](#search-documentation)

Full-text search within an agent's knowledge base (RAG chunks).

**Scope:** `knowledge:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

query

string

Yes

Text to search for in knowledge content

limit

number

No

Max results (default 20)

Useful for checking what content is indexed before a chat, or debugging RAG retrieval issues. ("Did the Tesira firmware notes page actually get crawled?")

* * *

### [get\_tag\_analytics# ](#get-tag-analytics)

Get tag usage statistics for an agent over a time period.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

**Returns:** Per-tag counts for total fires, active fires, removed fires, text-replaced count, avg similarity, and last fired timestamp.

* * *

### [get\_file\_analytics# ](#get-file-analytics)

Get file upload statistics for an agent: upload counts and total storage by MIME type.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

**Returns:** Breakdown for both chat session uploads and consumer brain files.

* * *

### [get\_moderation\_stats# ](#get-moderation-stats)

Get moderation statistics: how many conversations were frozen, had responses replaced, or triggered notifications.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

No

ISO date to filter from (defaults to last 30 days)

**Returns:** Tag fire counts broken down by action type (freeze, static text, notification, webhook, manually removed) and affected session count.

* * *

### [get\_popular\_apps# ](#get-popular-apps)

Get the most-used agents in your organization, ranked by session count and unique users.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

since

string

No

ISO date to filter from (defaults to last 30 days)

limit

number

No

Max results (default 10)

* * *

### [export\_conversations# ](#export-conversations)

Export conversations as JSON for an agent within a date range.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

since

string

Yes

ISO date to export from (e.g. `2026-01-01`)

until

string

No

ISO date to export until (defaults to now)

limit

number

No

Max sessions to export (default 100, max 500)

* * *

## [Tags# ](#tags)

Manage intent tags for message classification and automated responses.

### [list\_tags# ](#list-tags)

List all tags for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_tag# ](#get-tag)

Get details for a specific tag, including utterances.

**Scope:** `apps:read`

Parameter

Type

Required

Description

tag\_id

string

Yes

Tag ID

* * *

### [create\_tag# ](#create-tag)

Create a new intent tag.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Tag name

description

string

No

Tag description

utterances

string\[\]

No

Example phrases that match this tag

action

object

No

Action to take when tag matches

**Action types:**

-   `staticText`: Replace the AI response with fixed text.
-   `freeze`: Stop conversation flow.
-   `notification`: Send webhook or email alert.

**Example:**

code 

```
"Create a tag called 'truck-roll-needed' for my support agent with utterances like 'send a tech', 'come on site', 'we need someone in the room'"
```

* * *

### [update\_tag# ](#update-tag)

Update an existing tag.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

tag\_id

string

Yes

Tag ID

name

string

No

New name

utterances

string\[\]

No

New utterances

action

object

No

New action

* * *

### [delete\_tag# ](#delete-tag)

Delete a tag.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

tag\_id

string

Yes

Tag ID

* * *

### [list\_tag\_instances# ](#list-tag-instances)

List messages that matched a specific tag.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

tag\_id

string

No

Filter by specific tag (optional)

limit

number

No

Max results (default 50)

* * *

### [remove\_tag\_instance# ](#remove-tag-instance)

Soft-delete a specific tag detection instance from a message. The instance is marked as removed rather than permanently deleted.

**Scope:** `apps:write`

Parameter

Type

Required

Description

tag\_instance\_id

string

Yes

Tag instance ID to remove

* * *

### [generate\_utterances# ](#generate-utterances)

Generate training utterances for a tag using AI. Utterances are example phrases that should trigger the tag. More utterances means better detection accuracy.

**Scope:** `apps:write`

Parameter

Type

Required

Description

tag\_name

string

Yes

The tag name (e.g. `wants quote`, `network outage`)

tag\_description

string

Yes

Description of what this tag detects

count

number

No

Number of utterances to generate (default 20, max 100)

**Example:**

code 

```
"Generate 30 training utterances for a tag called 'projector lamp issue' for a higher-ed classroom support agent"
```

* * *

## [Evaluations# ](#evaluations)

Create and run quality tests for your agents. Run an eval suite over a tier-1 Crestron support agent before pushing prompt changes to production.

### [list\_evals# ](#list-evals)

List all evaluations for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_eval# ](#get-eval)

Get details for a specific evaluation.

**Scope:** `apps:read`

Parameter

Type

Required

Description

eval\_id

string

Yes

Evaluation ID

* * *

### [create\_eval# ](#create-eval)

Create a new evaluation with test cases for an agent.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Evaluation name

test\_cases

object\[\]

Yes

Array of test cases

evaluation\_method

string

No

`factuality`, `faithfulness`, `answer_relevancy`, `context_relevancy`, or `comprehensive` (default: `factuality`)

**Test case format:**

json 

```
{
  "input": "TSW-1070 is showing offline. What do I check first?",
  "expected_output": "Check the Cresnet bus power, verify the touch panel's IP via Toolbox, then check the control system's program for the device ID."
}
```

* * *

### [update\_eval# ](#update-eval)

Update an existing evaluation's name, test cases, or method.

**Scope:** `apps:write`

Parameter

Type

Required

Description

eval\_id

string

Yes

Evaluation ID

name

string

No

New name

test\_cases

object\[\]

No

Updated test cases

evaluation\_method

string

No

New evaluation method

* * *

### [delete\_eval# ](#delete-eval)

Delete an evaluation.

**Scope:** `apps:write`

Parameter

Type

Required

Description

eval\_id

string

Yes

Evaluation ID

* * *

### [run\_eval# ](#run-eval)

Run an evaluation against the agent to score its responses on the test cases.

**Scope:** `apps:write`

Parameter

Type

Required

Description

eval\_id

string

Yes

Evaluation ID

* * *

### [list\_eval\_results# ](#list-eval-results)

List past evaluation runs.

**Scope:** `apps:read`

Parameter

Type

Required

Description

eval\_id

string

Yes

Evaluation ID

limit

number

No

Max results

* * *

### [get\_eval\_result# ](#get-eval-result)

Get detailed results from a specific evaluation run.

**Scope:** `apps:read`

Parameter

Type

Required

Description

result\_id

string

Yes

Result ID

* * *

## [Custom Actions# ](#custom-actions)

Manage API integrations for your agents. Open a service ticket in your PSA, query a control system processor, push a status update to a project tracker.

### [list\_custom\_actions# ](#list-custom-actions)

List all custom actions for an agent.

**Scope:** `actions:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_custom\_action# ](#get-custom-action)

Get details for a specific custom action.

**Scope:** `actions:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

action\_id

string

Yes

Action ID

* * *

### [create\_custom\_action# ](#create-custom-action)

Create a new API integration.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Action name

description

string

Yes

What the action does

method

string

Yes

HTTP method (GET, POST, etc.)

url

string

Yes

API endpoint URL

headers

object

No

Request headers

body\_template

string

No

Request body template

parameters

object\[\]

No

Input parameters

> **Note:** Custom actions have complex schemas. See the Custom Actions Guide for detailed examples.

* * *

### [update\_custom\_action# ](#update-custom-action)

Update an existing custom action.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

action\_id

string

Yes

Action ID

(other fields)

various

No

Fields to update

* * *

### [delete\_custom\_action# ](#delete-custom-action)

Delete a custom action.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

action\_id

string

Yes

Action ID

* * *

### [test\_custom\_action# ](#test-custom-action)

Test a custom action by executing it with sample parameters.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

action\_id

string

Yes

Action ID

parameters

object

No

Test parameters to pass

* * *

## [MCP Integrations# ](#mcp-integrations)

Connect external MCP servers to your agents.

### [list\_mcp\_integrations# ](#list-mcp-integrations)

List all connected MCP servers for an agent.

**Scope:** `actions:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_mcp\_integration# ](#get-mcp-integration)

Get details about a connected MCP server.

**Scope:** `actions:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

integration\_id

string

Yes

Integration ID

* * *

### [connect\_mcp\_server# ](#connect-mcp-server)

Connect an external MCP server to an agent.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

server\_url

string

Yes

MCP server URL (must be HTTPS)

name

string

No

Display name (defaults to server URL)

auth\_type

string

No

Authentication type: `NONE`, `BEARER`, or `OAUTH` (default: `NONE`)

auth\_token

string

No

Bearer token (when `auth_type` is `BEARER`)

* * *

### [update\_mcp\_integration\_tools# ](#update-mcp-integration-tools)

Enable or disable the entire MCP integration, or toggle specific tools by name.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

integration\_id

string

Yes

Integration ID

is\_active

boolean

No

Enable or disable the entire integration

enabled\_tools

string\[\]

No

Tool names to enable (unlisted tools are disabled)

* * *

### [disconnect\_mcp\_server# ](#disconnect-mcp-server)

Remove an MCP server connection.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

integration\_id

string

Yes

Integration ID

* * *

### [list\_hosted\_integrations# ](#list-hosted-integrations)

List hosted integration providers connected to an agent (Google Drive, Gmail, Outlook, OneDrive, Slack, and others).

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** For each integration: `provider`, `label`, `is_active`, `account_email`, and `requires_consumer_auth`.

* * *

## [Deployments# ](#deployments)

Manage multi-channel deployments (Slack, WhatsApp, Email, Voice).

### [list\_slack\_deployments# ](#list-slack-deployments)

List Slack workspace connections.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_slack\_deployment# ](#get-slack-deployment)

Get details about a Slack deployment.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

deployment\_id

string

Yes

Deployment ID

* * *

### [disconnect\_slack\_deployment# ](#disconnect-slack-deployment)

Remove a Slack connection.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

deployment\_id

string

Yes

Deployment ID

* * *

### [get\_whatsapp\_deployment# ](#get-whatsapp-deployment)

Get WhatsApp business configuration.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_voice\_config# ](#get-voice-config)

Get voice agent configuration.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_voice\_config# ](#update-voice-config)

Update voice agent settings.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

voice\_id

string

No

Voice model ID

language

string

No

Language code

telephony\_enabled

boolean

No

Enable phone number

* * *

### [get\_email\_deployment# ](#get-email-deployment)

Get email channel configuration.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_email\_deployment# ](#update-email-deployment)

Update email channel settings.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

enabled

boolean

No

Enable/disable email

from\_name

string

No

Sender display name

* * *

### [get\_discord\_deployment# ](#get-discord-deployment)

Get the Discord bot integration status for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** `connected`, `discord_app_id`, `is_active`, and connection timestamp.

* * *

### [get\_github\_deployment# ](#get-github-deployment)

Get the GitHub App integration status for an agent (auto-respond to issues and PRs).

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** `connected`, `account_login`, `auto_respond_issues`, and installation details.

* * *

## [Consumers# ](#consumers)

Manage end-users (consumers) of your agents. The end-users in this case might be your client's employees, your field techs, or anyone else hitting the agent.

### [list\_consumers# ](#list-consumers)

List consumers of an agent with search and filtering.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

search

string

No

Search by name, email, or identifier

has\_email

boolean

No

Filter to consumers with/without email

sort\_by

string

No

`created_at`, `credits`, `name`, or `email` (default: `created_at`)

sort\_dir

string

No

`asc` or `desc` (default: `desc`)

limit

number

No

Max results (default 25, max 100)

offset

number

No

Pagination offset (default 0)

* * *

### [get\_consumer# ](#get-consumer)

Get details about a specific consumer including their session count.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

consumer\_id

string

Yes

Consumer ID

* * *

### [update\_consumer# ](#update-consumer)

Update a consumer's credit balance or subscription status.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

consumer\_id

string

Yes

Consumer ID

credits

number

No

Set credit balance (integer >= 0)

subscription\_active

boolean

No

Enable or disable the subscription

* * *

### [get\_user\_memories# ](#get-user-memories)

Get the AI memories stored for a specific consumer. Facts and context the agent has learned across conversations (which rooms a tech typically services, the IT contact at a particular client site, the control system in place at each campus building).

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

consumer\_id

string

Yes

Consumer ID

memory\_type

string

No

Filter by memory type (optional)

limit

number

No

Max memories to return (default 50)

Only active (non-superseded) memories are returned.

* * *

## [Workspaces# ](#workspaces)

Manage workspaces and team members.

### [list\_workspaces# ](#list-workspaces)

List all workspaces you have access to.

**Scope:** `workspace:read`

Parameter

Type

Required

Description

(none)

* * *

### [get\_workspace# ](#get-workspace)

Get details about a specific workspace.

**Scope:** `workspace:read`

Parameter

Type

Required

Description

workspace\_id

string

Yes

Workspace ID

* * *

### [list\_workspace\_members# ](#list-workspace-members)

List members of a workspace.

**Scope:** `workspace:read`

Parameter

Type

Required

Description

workspace\_id

string

Yes

Workspace ID

* * *

### [create\_workspace# ](#create-workspace)

Create a new workspace in your organization.

**Scope:** `workspace:write`

Parameter

Type

Required

Description

name

string

Yes

Workspace name

**Example:**

code 

```
"Create a new workspace called Service Operations"
```

* * *

## [Billing# ](#billing)

View subscription and credit information.

### [get\_subscription# ](#get-subscription)

Get subscription details for an organization.

**Scope:** `billing:read`

Parameter

Type

Required

Description

(none)

* * *

### [get\_credits# ](#get-credits)

Get credit balance and usage.

**Scope:** `billing:read`

Parameter

Type

Required

Description

(none)

* * *

### [get\_usage# ](#get-usage)

Get LLM token usage and non-LLM usage events for the organization.

**Scope:** `billing:read`

Parameter

Type

Required

Description

since

string

No

ISO date to filter from (defaults to last 30 days)

* * *

### [get\_usage\_by\_app# ](#get-usage-by-app)

Get token usage broken down by agent for the organization.

**Scope:** `billing:read`

Parameter

Type

Required

Description

since

string

No

ISO date to filter from (defaults to last 30 days)

**Returns:** Per-agent totals for `call_count`, `total_input_tokens`, and `total_output_tokens`.

* * *

### [get\_capabilities# ](#get-capabilities)

Get a boolean map of all feature capabilities for the organization. What features are available based on tier, add-ons, and feature flags.

**Scope:** `billing:read`

Parameter

Type

Required

Description

(none)

* * *

## [Prompt Engineering# ](#prompt-engineering)

AI-assisted tools for improving prompts and selecting models.

### [list\_available\_models# ](#list-available-models)

List all AI models available for use.

**Scope:** `apps:read`

Parameter

Type

Required

Description

(none)

* * *

### [generate\_system\_prompt# ](#generate-system-prompt)

Generate a new system prompt from a description.

**Scope:** `apps:write`

Parameter

Type

Required

Description

description

string

Yes

What the agent should do, its personality, and target audience

tone

string

No

Desired tone (professional, friendly, technical, casual)

* * *

### [improve\_system\_prompt# ](#improve-system-prompt)

Use AI to analyze and improve an existing system prompt.

**Scope:** `apps:write`

Parameter

Type

Required

Description

system\_prompt

string

Yes

The current system prompt to improve

focus

string

No

What to focus on: `clarity`, `safety`, `personality`, `instructions`, `all` (default: `all`)

* * *

### [recommend\_model# ](#recommend-model)

Get AI-powered model recommendations for your use case.

**Scope:** `apps:read`

Parameter

Type

Required

Description

use\_case

string

Yes

Description of the use case (e.g. tier-1 control system support, RFP scope generation)

priority

string

No

`quality`, `speed`, or `cost` (default: `quality`)

* * *

### [generate\_suggestions# ](#generate-suggestions)

Generate conversation starter suggestions for an agent based on its system prompt. These are the suggested messages shown to users to begin a conversation.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

count

number

No

Number of suggestions to generate (default 4, max 10)

style

string

No

`question`, `task`, `exploratory`, or `mixed` (default: `mixed`)

**Example:**

code 

```
"Generate 6 starter suggestions for my Q-SYS support agent"
```

* * *

## [Action Collections# ](#action-collections)

Manage reusable action bundles that can be linked to multiple agents.

### [list\_action\_collections# ](#list-action-collections)

List action collections owned by you or shared within your organization.

**Scope:** `actions:read`

Parameter

Type

Required

Description

workspace\_id

string

No

Filter by workspace

* * *

### [get\_action\_collection# ](#get-action-collection)

Get details for a specific action collection.

**Scope:** `actions:read`

Parameter

Type

Required

Description

collection\_id

string

Yes

Collection ID

* * *

### [create\_action\_collection# ](#create-action-collection)

Create a new action collection.

**Scope:** `actions:write`

Parameter

Type

Required

Description

name

string

Yes

Collection name

description

string

No

Collection description

workspace\_id

string

No

Workspace to create in

* * *

### [update\_action\_collection# ](#update-action-collection)

Update an action collection's name or description.

**Scope:** `actions:write`

Parameter

Type

Required

Description

collection\_id

string

Yes

Collection ID

name

string

No

New collection name

description

string

No

New collection description

* * *

### [delete\_action\_collection# ](#delete-action-collection)

Delete an action collection. Also removes it from any linked agents.

**Scope:** `actions:write`

Parameter

Type

Required

Description

collection\_id

string

Yes

Collection ID

* * *

### [link\_collection\_to\_app# ](#link-collection-to-app)

Link an action collection to an agent, making its actions available.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

collection\_id

string

Yes

Collection ID

* * *

### [unlink\_collection\_from\_app# ](#unlink-collection-from-app)

Remove an action collection from an agent.

**Scope:** `actions:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

collection\_id

string

Yes

Collection ID

* * *

### [list\_linked\_collections# ](#list-linked-collections)

List all action collections linked to a specific agent.

**Scope:** `actions:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [update\_collection\_sharing# ](#update-collection-sharing)

Update the sharing scope of an action collection.

**Scope:** `actions:write`

Parameter

Type

Required

Description

collection\_id

string

Yes

Collection ID

sharing\_scope

string

Yes

`PRIVATE`, `WORKSPACE`, or `PUBLIC`

-   **PRIVATE.** Only you can see it.
-   **WORKSPACE.** Anyone in your workspace can discover and link it.
-   **PUBLIC.** Visible in the marketplace.

* * *

### [import\_collection\_tools# ](#import-collection-tools)

Import tools from an action collection into an agent as standalone custom actions. Unlike `link_collection_to_app`, imported tools are independent copies you can modify freely without affecting the source collection.

**Scope:** `actions:write`

Parameter

Type

Required

Description

collection\_id

string

Yes

Collection ID to import from

app\_id

string

Yes

Agent ID to import into

**Returns:** Count of imported tools and any that were skipped due to slug conflicts.

* * *

## [Variables# ](#variables)

Manage agent variables (key-value configuration used by custom actions). Useful for per-client API keys, control system IPs, headend hostnames.

### [list\_app\_variables# ](#list-app-variables)

List all variables for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_app\_variable# ](#get-app-variable)

Get details for a specific agent variable.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

variable\_id

string

Yes

Variable ID

* * *

### [create\_app\_variable# ](#create-app-variable)

Create a new agent variable.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Variable name

label

string

No

Display label

type

string

No

Variable type

description

string

No

Variable description

required

boolean

No

Whether the variable is required

* * *

### [update\_app\_variable# ](#update-app-variable)

Update an agent variable's value, label, or description.

**Scope:** `apps:write`

Parameter

Type

Required

Description

variable\_id

string

Yes

Variable ID

value

string

No

New variable value

label

string

No

New display label

description

string

No

New description

* * *

### [delete\_app\_variable# ](#delete-app-variable)

Delete an agent variable.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

variable\_id

string

Yes

Variable ID

* * *

## [Heartbeat# ](#heartbeat)

Configure and monitor proactive messaging (heartbeat). Your agent reaching out to consumers on a schedule. Ideal for monthly health checks across a managed-services portfolio or weekly status pings to project stakeholders.

### [get\_heartbeat\_config# ](#get-heartbeat-config)

Get the heartbeat configuration for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

**Returns:** `enabled`, `every`, `prompt`, `checklist`, `targets`, and `model`.

* * *

### [update\_heartbeat\_config# ](#update-heartbeat-config)

Update heartbeat configuration. Set the interval, prompt, delivery channels, and model.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

enabled

boolean

No

Enable or disable heartbeat

every

string

No

Interval (e.g. `30m`, `1h`, `4h`, `1d`)

prompt

string

No

Custom prompt for heartbeat messages

checklist

string

No

Criteria for what the heartbeat should check

targets

string\[\]

No

Delivery channels: `whatsapp`, `slack`, `email`, `webchat`, `webhook`

model

string

No

LLM model to use for heartbeat messages

* * *

### [list\_heartbeat\_runs# ](#list-heartbeat-runs)

List recent heartbeat runs for an agent. Shows which consumers were contacted and outcomes.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

limit

number

No

Max results (default 20)

* * *

## [Agent Links# ](#agent-links)

Link agents together so one agent can call another as a tool during chat. A general-purpose AV front-desk agent can route programming questions to a Crestron specialist agent and DSP questions to a Biamp specialist agent.

### [list\_agent\_links# ](#list-agent-links)

List agents linked to an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [list\_available\_agents# ](#list-available-agents)

List agents available to link to an agent (agents in the same organization not already linked).

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [link\_agent# ](#link-agent)

Link another agent to this agent so it can be called as a tool during chat.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Source agent ID (the agent that will call the linked agent)

target\_app\_id

string

Yes

Target agent ID (the agent to link)

**Example:**

code 

```
"Link the 'Q-SYS Lua Specialist' agent to my 'AV Help Desk' agent"
```

* * *

### [unlink\_agent# ](#unlink-agent)

Remove an agent link.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Source agent ID

target\_app\_id

string

Yes

Target agent ID to unlink

* * *

## [Database Connections# ](#database-connections)

Manage external database connections attached to agents. Supported types: `postgres`, `mysql`, `mssql`, `bigquery`, `snowflake`, `clickhouse`. Connect a project tracker, an inventory database, or a service-ticket warehouse.

### [list\_database\_connections# ](#list-database-connections)

List external database connections for an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [get\_database\_connection# ](#get-database-connection)

Get details about a database connection.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

connection\_id

string

Yes

Connection ID

* * *

### [create\_database\_connection# ](#create-database-connection)

Create a new external database connection for an agent. Connection strings are encrypted at rest.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Display name

db\_type

string

Yes

`postgres`, `mysql`, `mssql`, `bigquery`, `snowflake`, or `clickhouse`

connection\_string

string

Yes

Connection string/DSN

default\_access\_level

string

No

`read` or `read_write` (default: `read`)

allowed\_tables

string\[\]

No

Restrict access to specific tables (all tables if omitted)

max\_rows

number

No

Max rows per query result (default: 1000)

* * *

### [delete\_database\_connection# ](#delete-database-connection)

Delete a database connection from an agent.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

connection\_id

string

Yes

Connection ID

* * *

### [test\_database\_connection# ](#test-database-connection)

Test a database connection and discover its schema (tables, columns, types).

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

connection\_id

string

Yes

Connection ID

* * *

## [Monetization# ](#monetization)

Manage credit packages that consumers can purchase within your agent. Useful if you sell branded AV expert agents directly to clients or end-users.

### [list\_consumer\_packages# ](#list-consumer-packages)

List credit packages available for consumers to purchase in an agent.

**Scope:** `apps:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

### [create\_consumer\_package# ](#create-consumer-package)

Create a new credit package for consumer purchase. Supports one-time and subscription packages.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

name

string

Yes

Package name (e.g. `Service Pack`)

type

string

Yes

`ONE_TIME` or `SUBSCRIPTION`

credits

number

Yes

Number of credits in the package

price\_cents

number

Yes

Price in cents (e.g. `999` = $9.99)

description

string

No

Package description

billing\_interval

string

No

For subscriptions: `month` or `year` (default: `month`)

sort\_order

number

No

Display order (lower = first, default: 0)

* * *

### [update\_consumer\_package# ](#update-consumer-package)

Update a consumer credit package.

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

package\_id

string

Yes

Package ID

name

string

No

New name

credits

number

No

New credit amount

price\_cents

number

No

New price in cents

description

string

No

New description

is\_active

boolean

No

Enable/disable

status

string

No

`DRAFT` or `PUBLISHED`

sort\_order

number

No

New display order

* * *

### [delete\_consumer\_package# ](#delete-consumer-package)

Delete a consumer credit package (soft delete).

**Scope:** `apps:write`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

package\_id

string

Yes

Package ID

* * *

### [get\_monetization\_stats# ](#get-monetization-stats)

Get monetization analytics for an agent: total revenue, purchases, active subscriptions, and unique customers.

**Scope:** `analytics:read`

Parameter

Type

Required

Description

app\_id

string

Yes

Agent ID

* * *

## [Appendix# ](#appendix)

### [Permission scopes# ](#permission-scopes)

Scope

Description

`apps:read`

Read agent configurations

`apps:write`

Create, update, delete agents

`knowledge:read`

Read knowledge sources

`knowledge:write`

Manage knowledge sources

`actions:read`

Read custom actions

`actions:write`

Manage custom actions

`analytics:read`

Read analytics data

`workspace:read`

Read workspace info

`billing:read`

Read billing data

`*`

All permissions

### [Common error codes# ](#common-error-codes)

Code

Description

Resolution

`UNAUTHORIZED`

Invalid or expired token

Re-authenticate

`FORBIDDEN`

Insufficient scope

Request additional scopes

`NOT_FOUND`

Resource doesn't exist

Check the ID is correct

`RATE_LIMITED`

Too many requests

Wait and retry

`VALIDATION_ERROR`

Invalid parameters

Check parameter types and values

* * *

## [Next steps# ](#next-steps)

-   Common Workflows. Step-by-step examples.
-   Rate Limits. Usage limits and best practices.
-   Authentication. Token management.

\*AVCodex · Your AV expertise. Amplified by AI.\*

Was this helpful? 

[Edit this page →](#)

[

Previous

Authentication

](/docs/guides/authentication)[

Next

Common Workflows

](/docs/guides/common-workflows)

On this page

-   [Quick reference](#quick-reference)
-   [Apps](#apps)
-   [list\_apps](#list-apps)
-   [get\_app](#get-app)
-   [create\_app](#create-app)
-   [update\_app](#update-app)
-   [delete\_app](#delete-app)
-   [chat\_with\_app](#chat-with-app)
-   [search\_apps](#search-apps)
-   [publish\_app](#publish-app)
-   [list\_app\_versions](#list-app-versions)
-   [duplicate\_app](#duplicate-app)
-   [restore\_app\_version](#restore-app-version)
-   [rollback\_app\_version](#rollback-app-version)
-   [get\_app\_url](#get-app-url)
-   [Configuration](#configuration)
-   [get\_system\_prompt](#get-system-prompt)
-   [update\_system\_prompt](#update-system-prompt)
-   [get\_model](#get-model)
-   [update\_model](#update-model)
-   [get\_settings](#get-settings)
-   [update\_settings](#update-settings)
-   [update\_branding](#update-branding)
-   [list\_suggestions](#list-suggestions)
-   [update\_suggestions](#update-suggestions)
-   [Knowledge Sources](#knowledge-sources)
-   [list\_knowledge\_sources](#list-knowledge-sources)
-   [get\_knowledge\_source](#get-knowledge-source)
-   [add\_url\_source](#add-url-source)
-   [add\_text\_source](#add-text-source)
-   [delete\_knowledge\_source](#delete-knowledge-source)
-   [refresh\_knowledge\_source](#refresh-knowledge-source)
-   [list\_active\_crawls](#list-active-crawls)
-   [cancel\_crawl](#cancel-crawl)
-   [add\_document\_source](#add-document-source)
-   [get\_crawl\_progress](#get-crawl-progress)
-   [link\_knowledge\_source](#link-knowledge-source)
-   [unlink\_knowledge\_source](#unlink-knowledge-source)
-   [list\_linked\_knowledge\_sources](#list-linked-knowledge-sources)
-   [Analytics](#analytics)
-   [get\_app\_analytics](#get-app-analytics)
-   [search\_conversations](#search-conversations)
-   [get\_conversation](#get-conversation)
-   [get\_top\_queries](#get-top-queries)
-   [get\_model\_usage](#get-model-usage)
-   [get\_response\_time\_analytics](#get-response-time-analytics)
-   [get\_user\_engagement](#get-user-engagement)
-   [search\_messages](#search-messages)
-   [search\_documentation](#search-documentation)
-   [get\_tag\_analytics](#get-tag-analytics)
-   [get\_file\_analytics](#get-file-analytics)
-   [get\_moderation\_stats](#get-moderation-stats)
-   [get\_popular\_apps](#get-popular-apps)
-   [export\_conversations](#export-conversations)
-   [Tags](#tags)
-   [list\_tags](#list-tags)
-   [get\_tag](#get-tag)
-   [create\_tag](#create-tag)
-   [update\_tag](#update-tag)
-   [delete\_tag](#delete-tag)
-   [list\_tag\_instances](#list-tag-instances)
-   [remove\_tag\_instance](#remove-tag-instance)
-   [generate\_utterances](#generate-utterances)
-   [Evaluations](#evaluations)
-   [list\_evals](#list-evals)
-   [get\_eval](#get-eval)
-   [create\_eval](#create-eval)
-   [update\_eval](#update-eval)
-   [delete\_eval](#delete-eval)
-   [run\_eval](#run-eval)
-   [list\_eval\_results](#list-eval-results)
-   [get\_eval\_result](#get-eval-result)
-   [Custom Actions](#custom-actions)
-   [list\_custom\_actions](#list-custom-actions)
-   [get\_custom\_action](#get-custom-action)
-   [create\_custom\_action](#create-custom-action)
-   [update\_custom\_action](#update-custom-action)
-   [delete\_custom\_action](#delete-custom-action)
-   [test\_custom\_action](#test-custom-action)
-   [MCP Integrations](#mcp-integrations)
-   [list\_mcp\_integrations](#list-mcp-integrations)
-   [get\_mcp\_integration](#get-mcp-integration)
-   [connect\_mcp\_server](#connect-mcp-server)
-   [update\_mcp\_integration\_tools](#update-mcp-integration-tools)
-   [disconnect\_mcp\_server](#disconnect-mcp-server)
-   [list\_hosted\_integrations](#list-hosted-integrations)
-   [Deployments](#deployments)
-   [list\_slack\_deployments](#list-slack-deployments)
-   [get\_slack\_deployment](#get-slack-deployment)
-   [disconnect\_slack\_deployment](#disconnect-slack-deployment)
-   [get\_whatsapp\_deployment](#get-whatsapp-deployment)
-   [get\_voice\_config](#get-voice-config)
-   [update\_voice\_config](#update-voice-config)
-   [get\_email\_deployment](#get-email-deployment)
-   [update\_email\_deployment](#update-email-deployment)
-   [get\_discord\_deployment](#get-discord-deployment)
-   [get\_github\_deployment](#get-github-deployment)
-   [Consumers](#consumers)
-   [list\_consumers](#list-consumers)
-   [get\_consumer](#get-consumer)
-   [update\_consumer](#update-consumer)
-   [get\_user\_memories](#get-user-memories)
-   [Workspaces](#workspaces)
-   [list\_workspaces](#list-workspaces)
-   [get\_workspace](#get-workspace)
-   [list\_workspace\_members](#list-workspace-members)
-   [create\_workspace](#create-workspace)
-   [Billing](#billing)
-   [get\_subscription](#get-subscription)
-   [get\_credits](#get-credits)
-   [get\_usage](#get-usage)
-   [get\_usage\_by\_app](#get-usage-by-app)
-   [get\_capabilities](#get-capabilities)
-   [Prompt Engineering](#prompt-engineering)
-   [list\_available\_models](#list-available-models)
-   [generate\_system\_prompt](#generate-system-prompt)
-   [improve\_system\_prompt](#improve-system-prompt)
-   [recommend\_model](#recommend-model)
-   [generate\_suggestions](#generate-suggestions)
-   [Action Collections](#action-collections)
-   [list\_action\_collections](#list-action-collections)
-   [get\_action\_collection](#get-action-collection)
-   [create\_action\_collection](#create-action-collection)
-   [update\_action\_collection](#update-action-collection)
-   [delete\_action\_collection](#delete-action-collection)
-   [link\_collection\_to\_app](#link-collection-to-app)
-   [unlink\_collection\_from\_app](#unlink-collection-from-app)
-   [list\_linked\_collections](#list-linked-collections)
-   [update\_collection\_sharing](#update-collection-sharing)
-   [import\_collection\_tools](#import-collection-tools)
-   [Variables](#variables)
-   [list\_app\_variables](#list-app-variables)
-   [get\_app\_variable](#get-app-variable)
-   [create\_app\_variable](#create-app-variable)
-   [update\_app\_variable](#update-app-variable)
-   [delete\_app\_variable](#delete-app-variable)
-   [Heartbeat](#heartbeat)
-   [get\_heartbeat\_config](#get-heartbeat-config)
-   [update\_heartbeat\_config](#update-heartbeat-config)
-   [list\_heartbeat\_runs](#list-heartbeat-runs)
-   [Agent Links](#agent-links)
-   [list\_agent\_links](#list-agent-links)
-   [list\_available\_agents](#list-available-agents)
-   [link\_agent](#link-agent)
-   [unlink\_agent](#unlink-agent)
-   [Database Connections](#database-connections)
-   [list\_database\_connections](#list-database-connections)
-   [get\_database\_connection](#get-database-connection)
-   [create\_database\_connection](#create-database-connection)
-   [delete\_database\_connection](#delete-database-connection)
-   [test\_database\_connection](#test-database-connection)
-   [Monetization](#monetization)
-   [list\_consumer\_packages](#list-consumer-packages)
-   [create\_consumer\_package](#create-consumer-package)
-   [update\_consumer\_package](#update-consumer-package)
-   [delete\_consumer\_package](#delete-consumer-package)
-   [get\_monetization\_stats](#get-monetization-stats)
-   [Appendix](#appendix)
-   [Permission scopes](#permission-scopes)
-   [Common error codes](#common-error-codes)
-   [Next steps](#next-steps)

[](/)

The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry.

### Platform

-   What You Can Build
-   Templates
-   [Pricing](/pricing)

### Services

-   [Done-For-You](/pricing)
-   [Academy](/academy)
-   [Contact](/contact)

### Company

-   About
-   [The Signal](/blog)
-   [Docs](/docs)
-   [LinkedIn](#)

© 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant