Workflow API
Deploy agents that patrol web sources on a schedule, detect what changed, and deliver signals when conditions are met.
Lifecycle: active -> paused -> completed/failed
Credits: 1/execution (basic) | 2 (with NL condition) | Variable for multi-step/AI-planned
Workflow Modes
| Mode | Description | Key Config |
|---|---|---|
simple | Single agent patrol per execution (default) | workflow_type, operation_config |
multi_step | Multi-agent pipeline with dependencies | steps[] array |
ai_planned | Describe what to watch; AI generates the patrol pipeline | intent, max_credits_per_execution |
Step Types (for multi_step mode)
| Type | Description | Config Fields |
|---|---|---|
search | Web search | query, max_results, query_decomposition |
crawl | Web crawling | urls, max_pages, extraction_schema |
aggregate | Combine/summarize | aggregation_type, format |
Step Dependencies: depends_on (array of step IDs), output_key (reference name), cascade_condition (conditional execution)
POST /v1/workflows/assess-intent
Assess if a monitoring intent is specific enough for agents to patrol. FREE.
| Parameter | Type | Default | Description |
|---|---|---|---|
intent | String | required | The monitoring intent to assess (10-2000 chars) |
timeout | Number | 10000 | Timeout in milliseconds (1000-30000) |
Rate Limit: 10/hour/user
Response:
| Field | Type | Description |
|---|---|---|
assessment | String | specific or vague |
specificity_score | Number | 1-10 (7+ is specific enough) |
is_assessed | Boolean | false when assessment_source=fallback (system failure, not a real assessment) |
assessment_source | String | llm (full), heuristic (rate-limited), or fallback (LLM failed, defaults to specific/7) |
fallback_reason_code | String | timeout, parse_error, provider_error, rate_limited (only when source !== llm) |
vague_aspects | String[] | What's unclear (only if vague) |
proposed_intent | String | Clearer rewrite (only if vague) |
what_we_clarified | String[] | What was improved (only if vague) |
inferred | Object | Advisory metadata: trigger_conditions, exclusions, entities, source_types, suggested_cadence (hourly/daily/weekly/monthly), monitoring_type |
reasoning | String | Brief explanation |
POST /v1/workflows/plan
Preview an AI-planned patrol before deploying agents. Returns a complete workflow plan with recommended steps, topology, and quality scores.
Credits: Variable by preset — quick (~10), standard (~30), thorough (~50), comprehensive (~100). Returns 402 if insufficient.
Deprecated: The
phaseparameter and phased planning flow (discover → research → generate) were removed in March 2026. All planning now returns complete workflow plans in a single request. For async planning of complex workflows, usePOST /v1/workflows/plan/asyncand pollGET /v1/workflows/plan/async/{session_id}.
Core Parameters
| Parameter | Type | Description |
|---|---|---|
intent | String (required) | Natural language description (10-2000 chars) |
name | String | Optional workflow name |
max_credits_per_execution | Number | Execution budget limit |
planning_budget | Number | Planner budget hint (takes precedence over max_credits_per_execution) |
quality_mode | String | quality_first (default) or balanced |
skip_entity_discovery | Boolean | Skip entity discovery for faster response |
Response Fields
All responses include: planning_profile (precision_linear | dual_lane_hybrid | fork_join_dag), topology_reason, planning_quality_score, coverage_score, depth_score, coverage_gaps, recommended_steps, credits_consumed.
GET /v1/workflows
List workflows. Query: limit (1-100), offset, status (active/planning/plan_failed/archived), scope (all/owned/shared), search (string), tags (comma-separated), sort_by (created/updated/name), sort_order (asc/desc)
POST /v1/workflows
Create a new workflow. Describe what to watch, set a schedule, and deploy agents on patrol.
Core Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | String | Yes | Workflow name (max 255 chars) |
mode | String | No | simple (default), multi_step, ai_planned |
stop_condition | Object | Yes | When to complete workflow |
dry_run | Boolean | No | Estimate cost without creating |
Simple mode: workflow_type (search/crawl), operation_config
Multi-step: steps[] array
AI-planned: intent, max_credits_per_execution
Schedule Configuration (one required)
| Parameter | Description | Example |
|---|---|---|
interval | Human-readable ("N unit": minutes/hours/days/weeks) | "6 hours", "1 day" |
interval_minutes | Raw minutes (takes precedence over interval) | 60 |
cron_expression | 5-field cron | "0 9 * * MON,WED,FRI" |
scheduled_for | One-time ISO 8601 | "2025-01-15T15:00:00Z" |
anchor_minute | Align to minute (0-59) | 0 |
timezone | IANA timezone (default: UTC) | "America/New_York" |
Stop Condition Types
| Type | Description | Key Fields |
|---|---|---|
result_count | Result count meets condition | operator (>,<,>=,<=,==), value |
contains_url | Results contain specific URL | url |
field_value | Field matches value | field, operator, value |
extracted_field | Extracted crawl field matches | field, operator, value |
natural_language | LLM evaluates condition | description, confidence_threshold (default: 0.7) |
always | Never auto-stop | - |
NL Confidence: High (0.8-0.9) = strong evidence | Medium (0.6-0.7) = balanced | Low (0.4-0.5) = permissive
GET /v1/workflows/{workflow_id}
Get workflow details with recent executions.
PATCH /v1/workflows/{workflow_id}
Update workflow parameters.
Editable Fields: name, workflow_type, operation_config, stop_condition, interval_minutes, max_executions, status, session_id
DELETE /v1/workflows/{workflow_id}
Delete a workflow and stop scheduled patrols.
POST /v1/workflows/{workflow_id}/execute
Execute a patrol immediately. Supports dry_run: true.
Response: execution.credits, execution.condition_met, execution.result_changes
Result Change Tracking
For search workflows, compares against the immediately previous execution:
| Field | Description |
|---|---|
net_new_count | URLs not in previous execution |
dropped_count | URLs no longer in results |
retained_count | URLs in both executions |
change_rate | (new + dropped) / total_unique x 100 |
net_new_urls | Enriched data for new URLs (title, snippet, published_date) |
previous_execution_id | Previous execution (null for first) |
First execution counts all URLs as "new". For global uniqueness, use a Session (URL dedup via session_urls table).
Intent Relevance Filtering
The agent filters results not matching the workflow's monitoring intent. Intent extracted from: intent field > description > operation_config.query > name (fallback, filtering disabled).
Result classifications: NEW (relevant), CONTEXT (background), UPDATE (previously reported), IRRELEVANT (filtered).
Response includes intent_relevance_filter: filtered_count, filtered_items[] (url, title, reason), monitoring_intent_used.
When all changes are irrelevant, signal delivery is suppressed.