---
title: "Invoke a tool by name with a JSON body of its arguments. Runs the exact tool MCP would; acting (acts=true) tools require Infrastructure over REST."
method: POST
path: "/tools/{name}"
---

# Invoke a tool by name with a JSON body of its arguments. Runs the exact tool MCP would; acting (acts=true) tools require Infrastructure over REST.

`POST /tools/{name}`

## Request

- Base URL: `https://app.seomatic.ai/api/v1`
- URL: `https://app.seomatic.ai/api/v1/tools/{name}`
- Auth: HTTP bearer

## Path parameters

- `name` string, required

## Headers

- `X-Seomatic-Client` 'n8n' | 'make'
- `Idempotency-Key` string

## Request body

- object: The tool's argument object (per its input_schema).

## Response `200`

{ tool, result }: the tool answered. result is its output, usually a JSON string (parse it). A tool that refuses does NOT answer 200: it gets the matching 402/422/429/503 below, with its own output in result.

## Other responses

- `400`: Invalid arguments (INVALID_ARGUMENTS; details says what) or a malformed Idempotency-Key (INVALID_IDEMPOTENCY_KEY).
- `402`: Acting over REST requires Infrastructure (REST_ACT_REQUIRES_INFRA); the plan does not include acting through the API (SCOPE_REVOKED_BY_PLAN); X-Seomatic-Client is n8n or make and the workspace has no paid plan or trial (AUTOMATION_NOT_ENTITLED); the free monthly question limit is reached (FREE_QUOTA_EXCEEDED; body carries keep_going_url and a question_pack payment link); the subscription is paused or its card was declined (BILLING_INACTIVE; body links the one step that restores it, never an upgrade); or the tool refused for credits (INSUFFICIENT_CREDITS, PAYMENT_REQUIRED; body carries the tool result); or the tool hit a plan limit (the code is the refusal code itself: PROMPT_LIMIT, CADENCE_LIMIT, MONITOR_LIMIT, PAGE_LIMIT_EXCEEDED, SEAT_LIMIT_EXCEEDED, WORKSPACE_LIMIT_EXCEEDED, PLANNER_DISABLED, AUTO_EXECUTE_DISABLED, AGENT_SKILLS_NOT_ENTITLED, PAGE_TEMPLATES_NOT_ENTITLED, HOSTED_PAGES_NOT_ENTITLED, AI_ATTRIBUTION_NOT_ENTITLED, ZAPIER_NOT_ENTITLED, BYO_KEYS_NOT_ENTITLED, INCREMENTALITY_NOT_ENTITLED, WEBHOOKS_NOT_ENTITLED; `result` holds the tool refusal). Body carries upgrade_url (and reason, for tool refusals) where an upgrade is the fix.
- `403`: The plan allows it but the key creator's role in the workspace does not (FORBIDDEN_ROLE; e.g. a creator now a viewer calling an acting tool). No upgrade fixes it: an admin changes the role.
- `404`: Unknown or unauthorized tool (UNKNOWN_TOOL)
- `409`: A request with this Idempotency-Key is still running (IDEMPOTENCY_IN_PROGRESS; repeat after Retry-After to collect the result), or it ran and its answer was too large to keep (IDEMPOTENCY_RESULT_NOT_KEPT; it is not run again).
- `413`: Request body over 256 KB (BODY_TOO_LARGE). Tool arguments are small JSON objects.
- `422`: The tool refused: it needs a confirmation step first (NEEDS_CONFIRMATION), or it declined for another reason it states (TOOL_REFUSED); result holds its explanation. Or this Idempotency-Key was used for a different tool or arguments (IDEMPOTENCY_KEY_REUSED).
- `429`: Rate limited: the per-key tool-call limit (Retry-After header set), or the tool refused for a rate cap (e.g. ARTICLE_FAILURE_CAP; body carries the tool result).
- `502`: Tool execution failed (TOOL_FAILED)
- `503`: Temporarily unavailable, on our side, not a limit: the upstream data provider or the credit check is down (PROVIDER_UNAVAILABLE; nothing was charged), or idempotency is unavailable and the tool was NOT run (IDEMPOTENCY_UNAVAILABLE). Retry shortly.
- `504`: The tool is still running past the 60s response ceiling and was not stopped (TOOL_TIMEOUT). With an Idempotency-Key, repeat the request to collect its answer.

---

[API](https://skmtc.dev/seomatic/apis/seomatic-api.md) · [All operations](https://skmtc.dev/seomatic/apis/seomatic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/seomatic/apis/seomatic-api/revisions/113a2a263604?raw)