Flow (headless)

Dashboard-д api trigger-тэй, идэвхтэй (нийтлэгдсэн) flow-ыг серверээсээ дуудна. Харилцагч руу юу ч илгээгдэхгүй — flow-ийн «илгээсэн» мессежүүд хариунд messages болж ирнэ. Функц унтраалттай үед гурван route энгийн 404 {code:"not_found"} өгнө. Invoke нь багцад flows модуль шаардана (403 module_inactive); GET /v1/flows ба GET runs модулийг шалгадаггүй, багц буурсан ч өмнөх api flow-ууд ба гүйлтүүд уншигдсаар байна.

Endpoint-уудХолбоос хуулах

• GET /v1/flows → {flows:[{id, name, description, status, published_version, updated_at}]} — зөвхөн api trigger-тэй идэвхтэй flow.
• POST /v1/flows/:id/invoke {input: {…} (объект, ≤16KB, ≤5 түвшин), session_id?, stream?} + толгой Idempotency-Key (заавал биш) → 200 {status: completed|waiting|failed, session_id?, run_id, output, messages[], usage{tokens, cost_usd, billable_units}, error?{code, message}}. messages[] нь {type: text|quick_replies|buttons|carousel, text?, quick_replies?, buttons?, cards?, guard_blocked?} — guard_blocked:true бол AI-ийн текст хамгаалалтад баригдаж аюулгүй орлуулах текстээр солигдсон.
• GET /v1/flows/:id/runs/:runId → {run{id, flow_id, status, current_node_id, nodes_executed, vars, output, error?, started_at, completed_at?}, node_runs[{node_id, node_type, started_at, duration_ms, input, output, error?, tokens, cost_usd}]} — зөвхөн энэ workspace-ийн api flow-ийн API гүйлт (чатын гүйлт уншигдахгүй ⇒ 404 run_not_found).

HTTP код нь хүсэлтийнх, status нь гүйлтийнх. Гүйлт доторх алдаа — quota_exceeded (багцын AI хариу дууссан) · module_inactive (AI node-д flow_ai эсвэл script node-д flow_script багцад алга; flow_script модуль — Тун удахгүй) · run_budget_exceeded (60с эсвэл 200 node) · node_failed — нь 200 + status:"failed" + error.code; трейсийг GET runs/:runId-аас. HTTP 4xx/5xx = гүйлт ЭХЛЭЭГҮЙ.

Session (асуулт-хариулт)Холбоос хуулах

status:"waiting" = flow асуулт тавьсан. Хариултыг {session_id, input:{text:"…"}}-ээр 1 цагийн дотор (started_at-аас) үргэлжлүүлнэ; хугацаа өнгөрвөл 410 session_expired, зэрэг хоёр continue ⇒ 409 session_busy, дууссан гүйлт session биш ⇒ 404 session_not_found. Continue-д зөвхөн input.text уншигдана — vars.input нь ЭХНИЙ дуудлагынх хэвээр.

Зөвшөөрөгдсөн nodeХолбоос хуулах

Headless гүйлт харилцагч/ярианы контексгүй тул зөвхөн: start (trigger) · send_message · question · condition · variable · http · llm · knowledge · intent · extract · loop · call_flow (Тун удахгүй) · script (flow_script модуль — Тун удахгүй) · end. call_flow (Тун удахгүй)-ийн дуудагдах flow (ижил workspace, идэвхтэй, асуулт/хүлээлтгүй, гүн ≤3) мөн энэ жагсаалтаар шалгагдана — тохирохгүй node-той бол 200 + status:"failed".

script node нь багцад flow_script модуль шаардана (flow_script модуль — Тун удахгүй); байхгүй бол гүйлт 200 + status:"failed" + error.code:"module_inactive" (GET runs-ийн node error нь flow_script_module_inactive). loop · call_flow · condition-ийн олон салаа (cases) · delay until · variable-ийн op-ууд (Тун удахгүй) ба script (flow_script модуль — Тун удахгүй) нь платформ дээр үе шаттайгаар нээгдэнэ — нээгдээгүй үед тэр node-той flow нийтлэгдэхгүй.

Бусад (tool · delay · ai_response · handover · tag · assign · order · resume_ai · submit_form · set_variable/webhook_call-аас бусад v1 action · file төрлийн асуулт · capture_contact асаалттай extract) ⇒ 422 flow_not_invokable (node-ийг нэрлэнэ). Шалгалт invoke бүрд — flow-оо засаад нийтэлмэгц хүчинтэй. Dashboard-ийн flow canvas-ийн «API» самбар тохирохгүй node-ыг урьдчилан харуулна.

КвотХолбоос хуулах

Invoke өөрөө «AI хариу» болж тоологдохгүй; зөвхөн llm · intent · extract node амжилттай гүйвэл чатынхтай ЯГ ижил нэгж зарцуулна (usage.billable_units) — llm node бүр нэг нэгж (одоогоор Gemini-ийн default model; өөр model/provider сонгох (Тун удахгүй)); loop · call_flow (Тун удахгүй) · script (flow_script модуль — Тун удахгүй) өөрсдөө нэгж зарцуулахгүй (тэдний дотор гүйсэн AI node бүр тоологдоно). Workspace-д өдөрт 2,000 invoke (Улаанбаатарын шөнө дундаас; 429 daily_invoke_cap), зэрэг 4 гүйлт (429 concurrency_limited + Retry-After: 1) — stream ч тоологдоно.

Idempotency-KeyХолбоос хуулах

Idempotency-Key (≤128 printable ASCII, эс бөгөөс 400 idempotency_key_invalid) — 24 цагийн дотор ижил түлхүүр + ижил хүсэлт ⇒ анхны хариу + толгой Idempotent-Replayed: true, flow дахин гүйхгүй.

• Хүсэлтийн тэмдэг нь ТҮҮХИЙ body дээр (method + path + body байт) — whitespace, түлхүүрийн дараалал өөр JSON нь «өөр хүсэлт» ⇒ 422 idempotency_key_reuse. Давтахдаа яг ижил байтыг илгээ.
• Replay нь хадгалсан JSON-ыг утгаараа (semantic) ижил буцаана, байт-ижил биш (түлхүүрийн дараалал/зай өөр байж болно) — хариуг задлан уншиж харьцуул, байтаар бүү харьцуул.
• Анхны хариу 16KB-аас их байсан бол replay нь 409 idempotency_response_unavailable + run_id — хариуг GET /v1/flows/:id/runs/:runId-аас унш (flow дахин гүйхгүй, түлхүүр хэрэглэгдсэн хэвээр).
• Анхны хүсэлт гүйж байхад давтвал 409 idempotency_in_progress; 5 минутаас удаан «гүйж байгаа» (тасарсан) дуудлагын түлхүүр чөлөөлөгдөж шинэ гүйлт эхэлнэ.
• Гүйлт эхлэхээс өмнө татгалзсан хүсэлт (404/403/422/410/409 session, 503) түлхүүрийг ЭЗЛЭХГҮЙ — засаад ижил түлхүүрээр дахин илгээж болно. Гүйлтийн үр дүн (failed ч) replay болно.
• Replay болон idempotency_in_progress хариу ч зэрэг гүйлтийн слот шаарддаг — 4 слот бүгд завгүй үед давталт 429 concurrency_limited авч болно (Retry-After-ийн дараа дахин).

Stream (SSE)Холбоос хуулах

body-д stream: true эсвэл толгой Accept: text/event-stream ⇒ text/event-stream. Зөвхөн Authorization: Bearer — түлхүүрийг query-д ХЭЗЭЭ Ч; browser EventSource дэмжигдэхгүй, сервер-хооронд л. Event-ууд: run_start {run_id} → node бүрд node_start {node_id, type} … message {…} … node_end {node_id, type, ms, tokens, error?} → end {status, session_id?, output, usage, error?}; 15с тутам : ping.

• node_end-д input/output БАЙХГҮЙ — трейсийг GET runs/:runId-аас. end-д messages байхгүй (аль хэдийн message event-ээр ирсэн).
• Хязгаарт (хугацаа/node тоо) баригдсан node-д сервер node_start-ыг нөхөж илгээнэ — ийм node_start-ын дараа тэр дороо error-той node_end ирнэ (node үнэндээ гүйгээгүй). Client хос бүрийг node_id-аар тааруулна.
• Гүйлт эхлэхээс өмнөх алдаа энгийн JSON хариу (доорх кодууд) хэвээр — Content-Type-аа шалга.
• Холболт тасарвал гүйлт зогсож failed болж хадгалагдана; тэр түлхүүрийн replay нь тэр failed хариуг буцаана. Тасарсан stream-ийг дахин оролдохдоо ШИНЭ Idempotency-Key өг.
• Ижил Idempotency-Key-ийн давталт stream хүсэлтэд ч JSON (синхрон хариуны бие) буцаана, stream биш.

Алдааны кодуудХолбоос хуулах

404 not_found (функц унтраалттай үед) · flow_not_found · session_not_found · run_not_found · 410 session_expired · 409 session_busy · idempotency_in_progress · idempotency_response_unavailable · 422 flow_not_invokable · idempotency_key_reuse · 400 input_invalid · idempotency_key_invalid · 403 module_inactive · 429 daily_invoke_cap · concurrency_limited · 500 internal_error · 503 guard_not_wired (flow түр ажиллах боломжгүй — дахин оролдоно).