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

namestring required

Tool name from GET /tools.

Headers

X-Seomatic-Client'n8n' | 'make'

Identifies an automation-platform integration (the official n8n node sends n8n, the Make app sends make). When set, every call, including a connection test against /me, requires a paid plan or a trial (reads work on any of them; acting tools still need Infrastructure), else 402 AUTOMATION_NOT_ENTITLED. Omit it for plain REST usage.

Idempotency-Keystring

Makes the call safe to repeat (a UUID per logical call). The first request runs the tool; a repeat with the same key and arguments returns that run's response (header Idempotent-Replayed: true) or 409 IDEMPOTENCY_IN_PROGRESS while it still runs, and an ACTING tool (acts=true) is never run twice. Kept: acting calls for 24h; any call that outlived the 60s response (504 TOOL_TIMEOUT) for 24h if acting, 1h if a read. A fast read is not kept, so repeating it runs it again (harmless). Answers over 64 KB are returned once and not kept: a repeat gets 409 IDEMPOTENCY_RESULT_NOT_KEPT. Calls refused before running (400, 402, 403, 404, 429) are not kept, and neither is an acting call the tool refused for credits, a rate limit or a provider outage (402, 429, 503; nothing acted), so the key works again once fixed.

Request body

object required

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

Response

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

Changes

No recorded changes to this operation across all 1 revision of this API.