seo-connect

POST `/v1/seo-connection/research/{tool}`

Run one research report on the site. Spends credits when the plan lacks it.

Authentication

Send an API key as a bearer token. The endpoint checks sites.create; a key without it is refused with 403, not 404.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/seo-connection/research/{tool} \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{  }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

The same run as runVisibilityAudit (keyword_research, domain_score, competitors) on the site's own target, with the same refusals, workflow id and audit row; read the result from listVisibilityAudits. When the organization's plan does not include the product it is pay-per-use (one keyword_list or domain_report unit), needs seo.spend, and does NOT add the product to the site's schedule — one question is not a subscription.

Parameters

Name	Type	Required	What it is
`tool (path)`	`string<keywords, domain, gap>`	Yes	`keywords` — keyword research (around `seed`, for `page_url`, or for the whole site); `domain` — what the site's domain is worth in search; `gap` — who else ranks for the site's…

Request body

Name	Type	Required	What it is
`seed`	`string`	No	`keywords` only: suggestions around this phrase.
`page_url`	`string`	No	`keywords` only: one page of the site.
`location`	`string`	No	The market the question is asked in, in the customer's own words — "Germany", "de" — exactly as `TrackedKeyword.location`. Blank is the default market. A market that cannot be…
`language`	`string`	No	The results language for `location` ("de"). Blank is the default.
`competitor`	`string`	No	`gap` only: one rival domain. The run then also reads the phrases that domain ranks for and stores, as the audit summary's `gap`, the ones the site does not rank for (`keywords`:…

Response

Name	Type	Required	What it is
`workflow_id`	`string`	Yes	—
`kind`	`VisibilityAuditKind`	Yes	Which product an audit belongs to. `ai_visibility` — do the answer engines cite this site, and is it fit to be cited at all. `reputation` — ratings and recent reviews across…
`target_id`	`string`	Yes	—

Errors this endpoint can return

401 · 403 · 404 · 422 · 503

POST /v1/seo-connection/research/{tool}