seo-connect

POST `/v1/plugin-ai/complete`

Run the Zinn® SEO plugin's AI on Zinn® credits. Spends credits.

Authentication

Send an API key as a bearer token. The endpoint checks billing.view; 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/plugin-ai/complete \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "requests": <object[]> }'

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 alternative to the site owner's own AI key in the plugin (zs-197): up to 20 independent requests in one call, run concurrently, each metered on the one Zinn® AI meter (surface plugin_ai) and debited from the connected site's org — filed against the site, so its monthly limit and the agency overview count it. A request that fails is reported in place (ok: false with a failure) and charged nothing; the others still return. A schema (a JSON object schema) asks for a structured answer, returned as data. The model is the cheapest one we have verified and can price. Needs the seo.spend scope. Refused before anything is sent or spent (403, with a failure of class refused): no Zinn® credit (the app's free daily allowance is never used by the plugin), the site's monthly limit, or an account not in good standing. When EVERY request failed, 503 with the failure of the first: provider_outage names the AI vendor and its status page; our_fault names nobody.

Request body

Name	Type	Required	What it is
`requests`	`object[]`	Yes	—
`purpose`	`string`	No	What the plugin used it for (usage log only).

Response

Name	Type	Required	What it is
`funding`	`string<credits, byo>`	Yes	`byo`: the org's own key saved in Zinn® paid, and nothing was charged.
`charged_micros`	`integer`	Yes	Total Zinn® credits debited by this call
`balance_micros`	`integer`	Yes	The org's balance after this call.
`currency`	`string<USD>`	Yes	—
`results`	`object[]`	Yes	—

Errors this endpoint can return

401 · 403 · 422 · 429 · 503

POST /v1/plugin-ai/complete