rankwatchAPI
Log in

Tools jobs

Run RankWatch tools asynchronously via the API — create, poll, idempotency, delete.

Tool endpoints run the same RankWatch tools available in the product, as asynchronous jobs.

Paths

POST   /workspaces/{workspace_id}/tools/{tool_slug}/jobs
GET    /workspaces/{workspace_id}/tools/{tool_slug}/jobs
GET    /workspaces/{workspace_id}/tools/{tool_slug}/jobs/{job_id}
GET    /workspaces/{workspace_id}/tools/{tool_slug}/jobs/{job_id}/result
DELETE /workspaces/{workspace_id}/tools/{tool_slug}/jobs/{job_id}

Scopes: tools:write for create/delete; tools:read for list/get/result.

Topic Prompt Generator — API auto mode

Same product tool as Topic Prompt Generator. The API skips UI topic/audience approval.

topic-prompt-auto is a URL alias only — jobs appear in the product Topic Prompt Generator history.

POST …/tools/topic-prompt-auto/jobs          # or topic-prompt-generator with auto body
GET  …/tools/topic-prompt-auto/jobs          # list auto-mode jobs
GET  …/tools/topic-prompt-auto/jobs/{job_id} # status + phase (poll until completed|failed)
GET  …/tools/topic-prompt-auto/jobs/{job_id}/result  # prompts payload when completed

Tool slugs

  • brand-prompt-generator
  • ai-keyword-suggest
  • ai-checker
  • category-brand-lookup
  • category-prompt-generator
  • topic-discovery
  • topic-prompt-generator — classic (topics + audienceMix) or auto body (domain + topicCount, no topics)
  • topic-prompt-auto — alias for Topic Prompt Generator auto mode

Also available: GET /tools/entitlements and GET /tools/{tool_slug}/meta. Request bodies use camelCase field names, consistent with the product.

Topic Prompt Generator auto mode

Auto body (on topic-prompt-auto or topic-prompt-generator): { domain, topicCount (1–5), promptCount (5–100), brandName?, language?, locations?, refresh? }.

The server:

  1. Runs topic discovery
  2. Automatically selects the first topicCount topics
  3. Applies a default audience mix (60/30/10)
  4. Generates prompts

There is no approval step for topics, audiences, or competitors. Documented on tool meta as auto_selects_topics_and_audience: true.

Combined tool credits are charged on success (discovery + generate). Usage and cost are recorded when the job succeeds.

Deep dive

After a completed Topic Prompt Generator job (classic or auto):

POST /workspaces/{workspace_id}/tools/{tool_slug}/jobs/{job_id}/deep-dive
GET  /workspaces/{workspace_id}/tools/{tool_slug}/jobs/{job_id}/deep-dive

Use either topic-prompt-generator or the topic-prompt-auto alias in the path. Attach to an existing project (project_id) or create a new AI project with setups. Requires tools:write (+ projects:write when creating). Enqueues all prompt tracking batches server-side. Poll project status until ready.

Create requirements

  1. Header Idempotency-Key: <unique-string>
  2. Scope tools:write
  3. Sufficient credits and plan capacity

Poll GET …/jobs/{job_id} until the job reaches a terminal status, then read the result. Use DELETE when you no longer need the job record.

Credits

Job creation uses organization credits the same way as in-product tool runs. Check remaining credits with GET /account/usage/credits (usage:read).

Tools jobs · RankWatch API