# 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](https://docs.plugsight.app/developers/authentication.md)).

| 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](https://docs.plugsight.app/developers/errors.md).                                                                             |
| 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. Plugsight stores none of it; only short lists, such as which accounts a login reaches, are kept for a few minutes. |

## List the tools

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

```json
{
  "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](https://docs.plugsight.app/developers/accounts-tools.md).

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

```bash
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`:

```json
{
  "data": {
    "connector": "Google Analytics 4",
    "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](https://docs.plugsight.app/developers/errors.md).

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

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

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

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

## Related articles

- [Authentication](https://docs.plugsight.app/developers/authentication.md)
- [Errors](https://docs.plugsight.app/developers/errors.md)
- [Accounts tools](https://docs.plugsight.app/developers/accounts-tools.md)

---

Web version: https://docs.plugsight.app/developers/calling-tools
