Branch your workflow
Not every pipeline is a straight line. The Conditional Workflow API lets a task's outcome decide what happens next — route flagged content one way, clean content another — without you writing an if/else router between two separate API calls.
The if/else your pipeline actually needs
Suppose you run content moderation on an upload: if it's flagged, it needs a human review queue; if it's clean, it just needs to publish. Doing this with two plain API calls means your own code has to sit in the middle, inspect the first result, and decide which second call to make, and that decision logic tends to sprawl once there's more than one condition to check. POST /flow/conditional lets you express that branch declaratively — the condition and both possible next steps travel together in one request, and the decision itself becomes part of the task definition instead of a piece of code you own.
How the branching is evaluated
You define a condition that reads a field from the previous step's output — a status, a score, a boolean — and two (or more) possible next steps tied to different outcomes of that condition. The platform evaluates the condition automatically once the prior step completes and only executes the branch that matches, never both, so there's no wasted work spent computing an outcome you were always going to discard.
What you get back
You still get one task_id for the whole conditional flow. The result tells you which branch actually ran, along with that branch's output, delivered through a signed webhook or a signed link valid for 24 hours — so downstream systems know not just the outcome, but the path taken to reach it, which is useful the moment someone asks why a particular item ended up where it did.
Failures and honesty about cost
Only the branch that actually executes can fail or succeed; the branch not taken is never invoked and never billed. A failing branch gets three retries before returning a clear, specific error, exactly like every other KIT task, and failed attempts are never charged, so a condition that correctly routes an item to a branch that then hits a bad input still tells you exactly where things went wrong.
Where conditionals belong
This task exists for the decision points that used to force you into custom orchestration: approve-or-reject flows, language-based routing, quality-threshold gates, anywhere the next step genuinely depends on what the last one found. Since it's a normal async task, a conditional step nests cleanly inside a chain or runs on a schedule, so decision logic doesn't have to live in a separate service you maintain yourself, and it can sit anywhere in a larger pipeline without special handling.
What you can do with it
Content moderation routing
Send flagged uploads to a review branch and clean uploads straight to a publish branch, based on the moderation score from the prior step.
Language-based translation gate
Only trigger translation when detected language differs from the target language, skipping the step entirely when it's already a match.
Quality threshold escalation
Route a transcription with a low-confidence score to a re-processing branch, and a high-confidence one straight to delivery.
Tiered customer response
Branch a support message to an automated reply when sentiment is neutral, or to a priority queue when sentiment reads as negative.
FAQ
How do I define the condition for branching?
You reference a field from the previous step's output — such as a status or score — in the request to POST /flow/conditional, along with the step to run for each possible outcome.
Is the Conditional Workflow API free?
There's no free tier — free tiers get abused and slow everyone down. Access runs on a prepaid ForHosting KIT balance: top up from $10.00 (it never expires) and each request is charged at its published price, so a call with no balance returns HTTP 402. No subscription, no tokens, no invented credits, and a failed task is never charged.
Do both branches run, or only the matching one?
Only the branch that matches the condition executes; the other is never invoked and never charged.
Can I have more than two possible branches?
Yes, you can define multiple conditions mapped to multiple next steps, not just a simple true/false split.
How do I know which branch ran?
The final result explicitly states which branch executed along with its output, so downstream systems can react to both the outcome and the path taken.
What happens if the branch that runs fails?
It's retried automatically up to three times; if it still fails, you get a specific error and no charge for the failed attempts.
Can a conditional step be part of a longer chain?
Yes, conditionals are standard async tasks, so they nest inside a chain or run as part of a scheduled flow just like any other step.
Is conditional routing the same as retry logic?
No, retries handle failures of a single task automatically; conditional routing decides which different task to run next based on a successful result.
For developers — API access
Everything on this page is available programmatically. This section is for teams who want to wire it into their own systems; everyone else can just use the tool above.
API endpoint
Prefer to automate it? One authenticated POST creates the task; the result comes back by webhook or a signed link. The same capability also runs here on the web, and soon from our app, email and Telegram.
Call it from your stack
curl -X POST https://api.kit.forhosting.com/flow/conditional \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"input":"…"}'const res = await fetch("https://api.kit.forhosting.com/flow/conditional", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"input": "…"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/flow/conditional",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"input": "…"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/flow/conditional", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"input":"…"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"input":"…"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/flow/conditional", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Example request
{
"input": "…"
}Example response
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "flow.conditional",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}The API is asynchronous: the call returns a task_id immediately and the result arrives by webhook. Polling is capped at 1 req/s per task.
Pricing
Published price — no tokens, no invented credits. A failed task is never charged.
Errors
| HTTP | Code | Meaning |
|---|---|---|
401 | unauthorized | Missing or invalid API key. |
402 | insufficient_balance | Your balance doesn't cover the task price. |
404 | unknown_type | That task type doesn't exist. |
429 | rate_limited | Too many requests. Use the webhook instead of polling. |