Docs/Guides/AVCodex MCP Server

    Tools Reference

    Last updated · MAR 2026·Read as Markdown

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

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

    Category Tools Description
    Apps 13 Create, publish, duplicate, rollback, and deploy agents
    Config 9 System prompts, models, settings, branding, suggestions
    Knowledge 13 Add URLs, documents, text, link sources, crawl monitoring
    Analytics 14 Usage data, conversations, metrics, search, moderation
    Tags 8 Intent tagging, classification, utterance generation
    Evals 8 Quality testing and evaluation
    Custom Actions 6 API integrations and testing
    MCP Integrations 6 External MCP servers and hosted integrations
    Deployments 10 Slack, WhatsApp, Discord, GitHub, Email, Voice
    Consumers 4 End-user management and memory
    Workspaces 4 Workspace management
    Billing 5 Subscription, credits, usage, capabilities
    Prompt Engineering 5 AI-assisted prompt improvement and suggestions
    Action Collections 10 Reusable action bundles with sharing
    Variables 5 Application config variables
    Heartbeat 3 Proactive messaging configuration and history
    Agent Links 4 Agent-to-agent delegation
    Database Connections 5 External database connections
    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.

    Core CRUD operations for managing AVCodex agents.

    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 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 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 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#

    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#

    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 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 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 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#

    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 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 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 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.

    Manage agent settings, system prompts, and branding.

    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 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 the AI model configuration for an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 detailed settings including RAG configuration.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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#

    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#

    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'"

    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 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 details about a specific knowledge source.

    Scope: knowledge:read

    Parameter Type Required Description
    source_id string Yes Knowledge source ID

    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 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#

    Remove a knowledge source from an agent.

    Scope: knowledge:write

    Parameter Type Required Description
    source_id string Yes Knowledge source ID

    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 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 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#

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

    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 knowledge sources linked to an agent from other agents (shared sources).

    Scope: knowledge:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    Access usage data, conversations, and metrics.

    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 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 a specific conversation with all messages.

    Scope: analytics:read

    Parameter Type Required Description
    session_id string Yes Session ID

    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 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 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 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 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#

    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 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 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 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 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 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)

    Manage intent tags for message classification and automated responses.

    list_tags#

    List all tags for an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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 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 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 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#

    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 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"

    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 all evaluations for an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    get_eval#

    Get details for a specific evaluation.

    Scope: apps:read

    Parameter Type Required Description
    eval_id string Yes Evaluation ID

    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 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 an evaluation.

    Scope: apps:write

    Parameter Type Required Description
    eval_id string Yes Evaluation ID

    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 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 detailed results from a specific evaluation run.

    Scope: apps:read

    Parameter Type Required Description
    result_id string Yes Result ID

    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 all custom actions for an agent.

    Scope: actions:read

    Parameter Type Required Description
    app_id string Yes Agent ID

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

    Connect external MCP servers to your agents.

    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 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 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#

    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#

    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 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.

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

    list_slack_deployments#

    List Slack workspace connections.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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#

    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 business configuration.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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 channel configuration.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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 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.

    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 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 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 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 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.

    Manage workspaces and team members.

    list_workspaces#

    List all workspaces you have access to.

    Scope: workspace:read

    Parameter Type Required Description
    (none)

    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 members of a workspace.

    Scope: workspace:read

    Parameter Type Required Description
    workspace_id string Yes Workspace ID

    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"

    View subscription and credit information.

    get_subscription#

    Get subscription details for an organization.

    Scope: billing:read

    Parameter Type Required Description
    (none)

    get_credits#

    Get credit balance and usage.

    Scope: billing:read

    Parameter Type Required Description
    (none)

    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 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 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)

    AI-assisted tools for improving prompts and selecting models.

    list_available_models#

    List all AI models available for use.

    Scope: apps:read

    Parameter Type Required Description
    (none)

    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#

    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#

    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 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"

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

    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 details for a specific action collection.

    Scope: actions:read

    Parameter Type Required Description
    collection_id string Yes Collection ID

    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 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 an action collection. Also removes it from any linked agents.

    Scope: actions:write

    Parameter Type Required Description
    collection_id string Yes Collection ID

    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

    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 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 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 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.

    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 all variables for an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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 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 an agent variable.

    Scope: apps:write

    Parameter Type Required Description
    app_id string Yes Agent ID
    variable_id string Yes Variable ID

    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 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 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 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)

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

    List agents linked to an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

    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 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"

    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

    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 external database connections for an agent.

    Scope: apps:read

    Parameter Type Required Description
    app_id string Yes Agent ID

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

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

    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#

    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
    • 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 →