Quickstart

You’ll need a FlowKoi account, a flow with a CLAUDE.md in your project, and 60 seconds at the keyboard.

1. Mint an API key

In the FlowKoi dashboard:

1. Open the project that contains your flow.
2. Settings → API → New API key.
3. Copy the key — it’s shown once (flo_…). Anything that can read it can spend your quota, so treat it like a password.

2. Find your flow ID

Same page, Flows tab. Each flow has a UUID — copy the one you want to invoke. Or list them programmatically:

curl https://api.flowkoi.com/api/v1/flows \
  -H "Authorization: Bearer $FLOWKOI_API_KEY"

import { FlowKoi } from "@flowkoi/sdk";
const flowkoi = new FlowKoi({ apiKey: process.env.FLOWKOI_API_KEY! });
console.log(await flowkoi.flows.list());

import os, httpx
r = httpx.get(
    "https://api.flowkoi.com/api/v1/flows",
    headers={"Authorization": f"Bearer {os.environ['FLOWKOI_API_KEY']}"},
)
print(r.json())

3. Trigger a run

curl https://api.flowkoi.com/api/v1/flows/$FLOW_ID/runs \
  -H "Authorization: Bearer $FLOWKOI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise the latest README change."}'

const run = await flowkoi.flows.run(flowId, {
  prompt: "Summarise the latest README change.",
});
console.log("Started", run.runId);

r = httpx.post(
    f"https://api.flowkoi.com/api/v1/flows/{flow_id}/runs",
    headers={"Authorization": f"Bearer {os.environ['FLOWKOI_API_KEY']}"},
    json={"prompt": "Summarise the latest README change."},
)
print(r.json()["data"]["runId"])

The response includes the runId, a streamUrl (SSE), and a wsUrl (WebSocket). Both are pre-signed; use whichever your runtime prefers.

4. Stream output

curl -N "https://api.flowkoi.com/api/v1/runs/$RUN_ID/stream?api_key=$FLOWKOI_API_KEY"

for await (const event of flowkoi.runs.stream(run.runId)) {
  if (event.type === "output") process.stdout.write(event.data);
  if (event.type === "finished") break;
}

with httpx.stream(
    "GET",
    f"https://api.flowkoi.com/api/v1/runs/{run_id}/stream",
    params={"api_key": os.environ["FLOWKOI_API_KEY"]},
    timeout=None,
) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):
            print(line[5:].strip(), flush=True)

The stream uses Server-Sent Events. See Streaming for the event format and the WebSocket alternative.

5. (Optional) Get notified when it finishes

Pass a callbackUrl at trigger time and FlowKoi will POST a signed payload to it the moment the run reaches a terminal state. Full details and verification recipe in Webhooks.

Where next

• Send follow-up messages — chat with a running agent without restarting it.
• Inject files mid-run — drop CSVs, configs, screenshots into the workdir while the agent runs.
• Webhooks — verify the HMAC signature and stop polling.
• Errors & retries — what every status code means and which to retry.