# Call a plugin tool

`POST https://api.vidmoat.com/v1/plugins/{slug}/{tool}`

- Scope: `plugins.invoke`
- Cost: provider-dependent

Invoke an available plugin tool with its arguments. Test keys return a fixture without contacting the plugin.

> **Note.** Replace SLUG and TOOL with an installed tool and supply arguments matching its schema. Live calls can have external effects or provider costs. Marketplace plugins need a paid plan; your own plugins work on any plan.

### Path parameters

- `slug` (string, required): The plugin slug.
- `tool` (string, required): The tool name (not the namespaced MCP name).

### Body

- `arguments` (object, optional, default `{}`): Arguments matching the tool's input schema.
- `projectId` (string, optional): Passed to the plugin as context only. It grants the plugin no access to the project.

## Response

Returns `200`.

### Response fields

- `ok` (boolean): `true`.
- `content` (any): What the plugin returned.
- `media` (object or null): When the tool produces media: `{ url, type }`, copied into your library.

> **Tip: With a test key.** Test keys return `{ "ok": true, "test": true, "note": … }` without calling the plugin.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 404 | [`not_found`](https://developer.vidmoat.com/developer/docs/errors#not_found) | The plugin or tool does not exist, is not installed, or is not available to you. |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | The plugin returned an error, needs a paid plan, or needs you to connect (or reconnect) your account to it. |
| 502 | [`provider_error`](https://developer.vidmoat.com/developer/docs/errors#provider_error) | The plugin timed out (20 seconds), was unreachable, redirected, returned more than 1 MB or bad JSON, or its media could not be copied. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/plugins/$SLUG/$TOOL \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{}}'
```

```js Node
const SLUG = 'YOUR_PLUGIN_SLUG';
const TOOL = 'YOUR_TOOL_NAME';

const res = await fetch(`https://api.vidmoat.com/v1/plugins/${SLUG}/${TOOL}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    arguments: {},
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

SLUG = "YOUR_PLUGIN_SLUG"
TOOL = "YOUR_TOOL_NAME"

res = requests.post(
    f"https://api.vidmoat.com/v1/plugins/{SLUG}/{TOOL}",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "arguments": {},
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{
  "ok": true,
  "content": [{ "type": "text", "text": "done" }],
  "media": { "url": "https://api.vidmoat.com/uploads/…png", "type": "image" }
}
```

---

Source: https://developer.vidmoat.com/developer/docs/api/plugins/invoke-plugin-tool
Previous: [List plugins](https://developer.vidmoat.com/developer/docs/api/plugins/list-plugins.md)
Next: [List bot users](https://developer.vidmoat.com/developer/docs/api/telegram-users/list-telegram-users.md)
All documentation: https://developer.vidmoat.com/llms-full.txt