agency-board

POST `/v1/agency/boards/{boardId}/ai/run`

Run one AI function on this board.

توثيقِ شناخت

ایک API کلید بطور بیر ٹوکن (bearer token) ارسال کریں۔ یہ اینڈ پوائنٹ اسپیسیفیکیشن میں کسی مخصوص اجازت کا ذکر نہیں کرتا، اس لیے فرض کرنے کے بجائے اپنی کلید کو کم از کم درکار اجازت دیں اور رسپانس چیک کریں۔

یہ اینڈ پوائنٹ کوئی آرگنائزیشن آئی ڈی نہیں لیتا۔ آپ کی کلید پہلے ہی اس آرگنائزیشن کی شناخت کرتی ہے جس سے یہ تعلق رکھتی ہے، اور اس کا جواب اسی کے مطابق محدود ہوتا ہے۔

آزمائیں

کوئی بھی چیز جو زاویہ دار قوسین میں ہو اسے اپنی اقدار سے بدلیں، اور کلیدی پلیس ہولڈر کو اپنے ڈیش بورڈ کی کسی کلید سے بدلیں۔

curl -X POST https://api.zinndigital.com/v1/agency/boards/{boardId}/ai/run \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "function": <string<draft_card, split_epic, summarise_card, summarise_board, triage_card, find_duplicates, release_notes, whats_blocked>> }'

لاگ ان ہیں؟ آپ کے ڈیش بورڈ میں موجود API کنسول آپ کی حقیقی تنظیم کی آئی ڈی اور آپ کی اپنی کلید خود بخود پُر کر دیتا ہے، اور لائیو API پر درخواست چلاتا ہے تاکہ آپ اصل ردعمل دیکھ سکیں۔ اس اینڈ پوائنٹ کو API کنسول میں کھولیں

تفصیلات

Runs a board AI function and returns its output. **A refusal to spend is a `200`, not a `4xx`.** When the org has no AI credit, no provider key, or is not in good standing, the response carries `skipped: true` with a `skipReason` and a customer-readable `text` — because the customer asked and we told them why not, which is a complete answer rather than a fault in their request. ⛔ A client reading `200` as "it ran" will record a success for a call that did nothing. **Read `skipped`.** `apply` defaults to `false`: AI on a board proposes and a person commits.

پیرامیٹرز

نام	قسم	لازمی	یہ کیا ہے
`boardId (path)`	`Uuid`	ہاں	Project board ID (UUIDv7).

درخواست کا باڈی

نام	قسم	لازمی	یہ کیا ہے
`function`	`string<draft_card, split_epic, summarise_card, summarise_board, triage_card, find_duplicates, release_notes, whats_blocked>`	ہاں	Which AI function to run.
`card_id`	`Uuid`	نہیں	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`apply`	`boolean`	نہیں	Write the result to the board. Defaults to false: AI on a board proposes and a person commits, so the irreversible half must be asked for explicitly.
`force`	`boolean`	نہیں	Re-run rather than replay. An identical call within 15 minutes is served from the previous run with no model call and no charge, so a retried automation cannot bill twice; `forc…
`options`	`object`	نہیں	Per-function input. `draft_card` takes `brief` and optionally `source`; `release_notes` takes `column_id`.

جواب

نام	قسم	لازمی	یہ کیا ہے
`function`	`string`	ہاں	—
`text`	`string`	ہاں	The output, or the reason it was skipped.
`payload`	`object`	نہیں	Structured result — labels, sub-tasks, candidate duplicates.
`model`	`string`	نہیں	The model that served it. Null on a skip, because none was chosen.
`provider`	`string`	نہیں	—
`funding`	`string<byo, credits, included>`	نہیں	Who paid. `byo` is the customer's own provider key; `credits` and `included` are Zinn®'s. All three are recorded on the same meter.
`usage_id`	`Uuid`	نہیں	The meter row, so board history and AI spend join up. Null on a skip.
`skipped`	`boolean`	ہاں	Read this. True means nothing ran and nothing was charged. A caller that treats `200` as "it worked" records a success for a call that did nothing.
`skip_reason`	`string`	نہیں	Machine-readable cause, e.g. `AI_BUDGET_EXHAUSTED`, `AI_NOT_IN_GOOD_STANDING`, `not_enough_discussion`, `nothing_blocked`.
`skip_kind`	`string<nothing_to_do, not_in_good_standing, not_entitled, unavailable>`	نہیں	The CLASS of the skip, beside its code. `nothing_to_do` is the product working (a healthy board has nothing blocked; a thread is too short to summarise) and is good news, not a…
`skip_params`	`object`	نہیں	The values the refusal sentence quotes (`count`, `column`), sent structurally so a client can render that sentence in the customer's own language rather than the engine's Englis…
`failure`	`VendorFailure`	نہیں	`CLAUDE.md` §57 — what to tell the customer about a refusal, as a stable message key plus a tone, so the dashboard renders the sentence in their own language. Present only on a…
`cached`	`boolean`	نہیں	Served from the previous identical run rather than the model.
`created_card_ids`	`Uuid[]`	نہیں	—
`run_id`	`Uuid`	نہیں	—

وہ خرابیان جو یہ اینڈ پوائنٹ واپس کر سکتا ہے

401 · 403 · 404 · 422

POST /v1/agency/boards/{boardId}/ai/run