Triggering Pipelines

ArkTeam runs can be triggered three ways: HTTP webhook (via ArkEvent), cron schedule (via ArkEvent), team-output events (via ArkEvent), and the ark trigger CLI command.

`ark trigger` (CLI)

The simplest trigger for testing and one-off runs:

ark trigger <team-name> -n <namespace> --input '{"topic": "your topic"}'

Options:

Flag	Description
`-n`	Namespace
`--input`	JSON object of input values. Overrides `spec.input` defaults.
`--watch`	Stream step output as the run progresses
`--sync`	Wait for the run to complete and print the output
`--timeout`	Maximum wait time (default: 60s)

ark trigger resets all steps to Pending and sets phase to Running. Succeeded steps from the previous run are not preserved — this is a full re-run.

To retry only failed steps, use ark retry:

ark retry <team-name> -n <namespace>
ark retry <team-name> -n <namespace> --step researcher   # retry one step

HTTP webhook trigger

Create an ArkEvent with source.type: webhook:

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: content-trigger
  namespace: my-org
spec:
  source:
    type: webhook
  targets:
    - team: content-pipeline

The operator creates a unique bearer-token secret and writes the webhook URL to .status.webhookURL:

kubectl get arkevent content-trigger -n my-org \
  -o jsonpath='{.status.webhookURL}'
# http://ark-operator.my-org.svc.cluster.local:8092/triggers/my-org/content-trigger/fire

Retrieve the bearer token:

TOKEN=$(kubectl get secret content-trigger-webhook-token -n my-org \
  -o jsonpath='{.data.token}' | base64 -d)

Synchronous mode (recommended)

Add ?mode=sync&timeout=120s to wait for the result inline:

curl -X POST \
  "http://ark-operator.my-org.svc.cluster.local:8092/triggers/my-org/content-trigger/fire?mode=sync&timeout=120s" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic": "distributed consensus"}'

Response:

{
  "status": "succeeded",
  "output": "Distributed consensus algorithms are...",
  "durationMs": 14200
}

Asynchronous mode

Omit ?mode=sync to return immediately with the task ID:

curl -X POST \
  "http://ark-operator.my-org.svc.cluster.local:8092/triggers/my-org/content-trigger/fire" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"topic": "distributed consensus"}'
# {"taskID": "1710000001-0"}

Exposing to localhost (local development)

kubectl port-forward svc/ark-operator 8092:8092 -n ark-system

Your app can now POST to http://localhost:8092/triggers/....

Fan-out to multiple teams

One event can trigger multiple teams in parallel:

spec:
  source:
    type: webhook
  targets:
    - team: content-pipeline
    - team: analytics-pipeline
    - team: notification-team

All three run simultaneously when the webhook is fired.

Cron trigger

Schedule a team run on a standard 5-field cron expression (UTC):

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: daily-report
  namespace: my-org
spec:
  source:
    type: cron
    cron: "0 8 * * *"    # 08:00 UTC every day
  targets:
    - team: report-team

Common schedules:

Schedule	Cron expression
Every hour	`0 * * * *`
Every day at 08:00 UTC	`0 8 * * *`
Every Monday at 09:00 UTC	`0 9 * * 1`
Every 15 minutes	`/15 * * *`

To inject input values on cron runs, set default inputs on the ArkTeam:

spec:
  input:
    topic: "weekly performance summary"
    format: "executive brief"

Team-output trigger

Chain two teams without embedding one inside the other. Fires when an upstream team completes:

apiVersion: arkonis.dev/v1alpha1
kind: ArkEvent
metadata:
  name: after-research
  namespace: my-org
spec:
  source:
    type: team-output
    teamOutput:
      name: research-team
      onPhase: Succeeded      # Succeeded | Failed | * (any terminal)
  targets:
    - team: summarize-team
    - team: index-team        # fan-out: both fire in parallel

The upstream team’s output is passed as the input to the triggered teams (available as ``).

Webhook integration: replacing a hardcoded LLM call

The most common use case: an existing application makes a direct LLM API call that you want to move to a managed agent.

Before:

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: `Extract: ${text}` }],
});

After:

const token = process.env.ARK_WEBHOOK_TOKEN;
const response = await fetch(
  "http://localhost:8092/triggers/ark-system/extract-trigger/fire?mode=sync&timeout=30s",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({ text }),
  }
);
const result = await response.json();
// result.output — the agent's response string

Your app code changes by one line. The prompt, model, and infrastructure are now managed by the operator.