ads

POST /v1/ads/asks

Ask a plain question about the organisation's own ads; the answer is checked figure by figure against cited facts (za-N7).

All ads endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

Send an API key as a bearer token. The key must carry the ads.view permission; a key without it is refused with 403, not 404.

Where your organisation id goes

This endpoint takes org_id as a field in the JSON body.

Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.

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/ads/asks \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "question": <string> }'

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

Gated on ads.view in ONE organisation (org_id in the body or X-Zinn-Org when the caller holds several). Interactive: one Zinn® AI call in the request, no job queue. The facts are read ONLY from the organisation's own synced figures (account totals, spend per day for up to 31 recent days, campaigns ranked by spend, Google keywords and search terms that spend with no conversion, open findings, changes waiting). status: answered (every number in answer appears in a fact it cites — ids in cites, figures in facts), facts_only (the written answer failed that check and is withheld; the cited facts are the answer), refused (no AI credit, or the organisation is not in good standing — error.failure class refused, nothing was spent) or failed (the AI provider failed — error.failure names the class: outage with its status page, a customer key problem, or ours). Who pays is the one meter's decision: the organisation's own AI key, else its Zinn® AI credit. At most ONE fix is offered, built from a fact (never by the model): pause_campaign or pause_keyword for a Google campaign or keyword that spends with no conversion. focus_day (za-285, "Ask your ads" from a chart point on /ads/analytics): the day the person clicked; that day's spend per account is always a fact, however far back inside days. 422 codes: askQuestion (1 to 500 characters), askDays (1 to 90), askNoAccounts, askHourly (60 asks per organisation per hour), askFocusDay (focus_day not a date inside the last days days). 404 for a connection_id that is not the organisation's.

Request body

NameTypeRequiredWhat it is
questionstringYes—
org_idstringNo—
connection_idstringNoNarrow to one ad account.
daysintegerNo—
localestringNoThe answer's language, e.g. en, ar.
focus_daystringNoza-285: the chart point (day) the question was asked from.

Response

NameTypeRequiredWhat it is
idstringYes—
questionstringYes—
localestringYes—
daysintegerYes—
connection_idstringYes—
statusstring<answered, facts_only, refused, failed>Yes—
answerstringYesEmpty unless answered. Fact ids appear in square brackets after the figures they back.
citesstring[]Yes—
factsAdsAskFact[]Yes—
fixobjectYes—
errorobjectYes—
created_atstringYes—

Errors this endpoint can return

401 · 403 · 404 · 422 · 429