PlugsightDocs

Calling tools

List the tools an API key can use, call one with JSON arguments, read the answer, pick an account and make changes with confirm.

The developer API has two endpoints. Both need your key in the Authorization header (see Authentication).

Endpoint What it does
GET /v1/tools Lists the tools this key can use, with their arguments.
POST /v1/tools/{name} Runs one tool. The JSON body is its arguments.

Basics

Base URL https://app.plugsight.app/v1 (HTTPS only)
Headers Authorization: Bearer <key> and, for POST, Content-Type: application/json
Success Status 200 with { "data": … }
Failure Status 4xx or 5xx with { "error", "message", "docs" }. See Errors.
Dates YYYY-MM-DD. Date-times in ISO 8601 with an offset, such as 2026-11-20T15:00:00+00:00.
Paging Tools with many results take limit and page, offset or page_token. Each tool's arguments say which.
Freshness Live: each call reads from the provider at that moment. Nothing is cached or stored by Plugsight.

List the tools

curl https://app.plugsight.app/v1/tools \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY"

The answer lists each tool with:

Field What it is
name The name to call it by.
title A short human name.
description What it does.
read_only true for tools that only read; false for tools that change something.
input_schema A JSON Schema of its arguments.
{
  "tools": [
    {
      "name": "list_accounts",
      "title": "List connected accounts",
      "description": "Lists the accounts this MCP can use…",
      "read_only": true,
      "input_schema": { "type": "object", "properties": {} }
    }
  ]
}

The list depends on the MCP server's connections. Add Zendesk to it and the Zendesk tools appear; remove Zendesk and they go. list_accounts and pagespeed_check are always there. The tool reference lists every tool by group, starting with Accounts.

Call a tool

Send a POST to /v1/tools/ followed by the tool's name. The body is a JSON object of its arguments. Send {} when it takes none.

curl -X POST https://app.plugsight.app/v1/tools/zendesk_ticket_stats \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-11-01", "to": "2026-11-15"}'

A successful answer is status 200 with the tool's result under data. What's inside data depends on the tool: usually an object or a list. For example, get_marketing_data:

{
  "data": {
    "connector": "Google Analytics",
    "date_range": { "from": "2026-10-17", "to": "2026-11-15" },
    "accounts": ["acme.com (properties/123456789)"],
    "columns": ["date", "sessions", "users"],
    "rows": [["2026-10-17", 412, 388], ["2026-10-18", 455, 419]],
    "row_count": 30,
    "totals": { "sessions": 13240, "users": 11872 }
  }
}

Most tools answer with JSON. If a tool's answer isn't JSON, data is a string of text.

If the tool can't run (a wrong argument, a change that isn't allowed, or the provider said no), you get 400 tool_error and a message saying what to fix. See Errors.

Choose an account

Many tools take an account argument.

  1. Call list_accounts to get each account's id.
  2. Pass that id as account.

If the MCP server has only one account of that kind, you can leave account out. With more than one, the tool returns an error listing the ids to choose from.

Marketing tools work differently: call list_marketing_accounts for the sites, properties and ad accounts the key reaches, and pass their ids as accounts. Leave accounts out to use all of them.

Making changes

Change tools, such as send_email, zendesk_add_comment or calendar_create_event, only run when all of these are true:

  • The request includes "confirm": true. This stops a change happening by accident. Set it only once your own code or your user has decided to go ahead.
  • The MCP server allows changes: Allow changes is ticked on its page.
  • The account allows changes: its switch under Write access on Connections is on.
  • Nothing is paused on the Permissions page.
  • The daily email limit isn't reached (for sending email). It's 20 emails per account in a rolling 24 hours unless you've changed it on Permissions.
curl -X POST https://app.plugsight.app/v1/tools/zendesk_add_comment \
  -H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticket_id": 1042, "body": "Thanks, your refund is on its way.", "public": true, "confirm": true}'

If one condition isn't met, you get 400 tool_error with a message naming it. Every change, and every blocked attempt, appears in Activity in the app.

A few change tools work differently:

  • create_draft saves a draft and never sends. It needs no confirm.
  • organize_emails marks, labels or moves emails. It needs no confirm, and stops only while email changes are paused.
  • zendesk_apply_macro previews first. Call it with preview left at true, then again with "preview": false and "confirm": true to apply it.

Code examples

Node.js

async function plugsight(tool, args = {}) {
  const res = await fetch(`https://app.plugsight.app/v1/tools/${tool}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PLUGSIGHT_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify(args),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error}: ${body.message}`);
  return body.data;
}

const stats = await plugsight("zendesk_ticket_stats", { from: "2026-11-01", to: "2026-11-30" });

Python

import os, requests

def plugsight(tool, **args):
    r = requests.post(f"https://app.plugsight.app/v1/tools/{tool}",
        headers={"Authorization": f"Bearer {os.environ['PLUGSIGHT_API_KEY']}"},
        json=args, timeout=60)
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{body['error']}: {body['message']}")
    return body["data"]

print(plugsight("woocommerce_sales_report", **{"from": "2026-11-08", "to": "2026-11-15"}))

Show data on your website

The key must stay secret, so don't call the API from a web page. Instead:

  1. Your web page calls a route on your own server, such as /api/stats.
  2. Your server adds the key, calls Plugsight, and keeps only the numbers the page needs.
  3. Cache the result for a few minutes, so you stay well under 120 requests a minute.

Serverless platforms work the same way: keep the key in the platform's environment variables.