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.
- Call
list_accountsto get each account'sid. - Pass that
idasaccount.
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_draftsaves a draft and never sends. It needs noconfirm.organize_emailsmarks, labels or moves emails. It needs noconfirm, and stops only while email changes are paused.zendesk_apply_macropreviews first. Call it withpreviewleft attrue, then again with"preview": falseand"confirm": trueto 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:
- Your web page calls a route on your own server, such as
/api/stats. - Your server adds the key, calls Plugsight, and keeps only the numbers the page needs.
- 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.