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)
GET /api/v1/workflows/assess-intent
Get documentation for the intent assessment endpoint.
POST /api/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, extraction_fields |
reasoning | String | Brief explanation |
GET /api/v1/workflows/plan
Get information about workflow planning capabilities.
POST /api/v1/workflows/plan
Preview an AI-planned patrol before deploying agents. Supports iterative phased planning (discover → research → generate) or one-shot full pipeline (default).
Credits: Variable by preset — quick (~10), standard (~30), thorough (~50), comprehensive (~100). Returns 402 if insufficient.
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 |
Phased Planning Parameters
| Parameter | Type | Description |
|---|---|---|
phase | String | discover, research, or generate. Omit for full pipeline. |
planning_session_id | UUID | Resume from previous phase. Required for research/generate. |
entity_overrides | Object | {add: [{name, type}], remove: [name]} |
research_feedback | String | Free-form guidance (e.g., "focus on enterprise") |
source_overrides | Object | {add: [url], remove: [url]} |
generation_overrides | Object | {topology_preference, step_guidance, max_steps} |
Phased Planning Flow
POST /plan {intent, phase: "discover"} → entities[], planning_session_id
POST /plan {planning_session_id, phase: "research"} → enrichment, classification
POST /plan {planning_session_id, phase: "generate"} → workflow steps, validation
POST /workflows {planning_session_id, mode: "ai_planned", stop_condition, interval}
Planning sessions expire after 2 hours. Each phase response includes: planning_session_id, phase, phase_complete, next_phase, credits.consumed_this_phase, credits.total_consumed.
Full Pipeline Response (phase omitted): planning_profile (precision_linear | dual_lane_hybrid | fork_join_dag), topology_reason, planning_quality_score, coverage_score, depth_score, coverage_gaps.
GET /api/v1/workflows/plan/{session_id}
Retrieve planning session state. Returns current_phase, accumulated outputs, overrides, credits_consumed, expires_at. Errors: 400 expired, 404 not found.
GET /api/v1/workflows/plan/stream
Get information about the streaming planning endpoint.
POST /api/v1/workflows/plan/stream
Stream planning progress via SSE. Same parameters as POST /api/v1/workflows/plan.
Key Events: started, entity_discovered, entity_enriched, workflow_generated, complete, error, heartbeat (15s)
GET /api/v1/workflows
List workflows. Query: limit (1-100), offset, status (active/paused/completed/failed)
GET /api/v1/workflows/analytics
Aggregate analytics. Query: range (1d/7d/30d/all), include_shared, status (CSV), mode (CSV), workflow_type (CSV).
Response: totals (workflows, executions, success rate, credits), timing (avg/p50/p95), composition, series (time-bucketed).
GET /api/v1/workflows/resume-all
Get counts of workflows paused by reason (credits_exhausted, subscription_expired, rate_limited).
POST /api/v1/workflows/resume-all
Resume auto-paused workflows. Optional pause_reason filter. Returns resumed_count, workflows[], credits.balance_after.
POST /api/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 |
recency_confidence_threshold | Number | No | Content recency filter confidence (0-1, default 0.50) |
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 /api/v1/workflows/{id}
Get workflow details with recent executions.
PATCH /api/v1/workflows/{id}
Update workflow parameters.
Editable Fields: name, workflow_type, operation_config, stop_condition, interval_minutes, max_executions, status, session_id, email_config, slack_config, notification_settings, recency_confidence_threshold, auto_adapt_config
Auto-Adapt Configuration (auto_adapt_config)
Controls the automatic application of baseline adaptation recommendations. Replaces the legacy auto_adapt boolean with granular policy control.
| Field | Type | Default | Description |
|---|---|---|---|
enabled | Boolean | true | Enable/disable auto-adapt for this workflow |
safe_threshold | Number | 0.70 | Minimum confidence for safe type auto-apply (0-1) |
safe_types | String[] | ["expand_step", "refine_step", "contract_step"] | Adaptation types eligible for auto-apply |
structural_mode | String | "off" | "off" or "safe_delete_only" — controls structural changes (step deletion) |
structural_safe_delete_threshold | Number | 0.95 | Minimum confidence for auto-delete (when structural_mode=safe_delete_only) |
max_auto_applies_per_baseline | Number | 3 | Maximum adaptations auto-applied per baseline execution |
Note: Cannot provide both auto_adapt_config and the legacy auto_adapt boolean in the same request.
Auto-Adapt Configuration (auto_adapt_config)
| Field | Type | Default | Description |
|---|---|---|---|
enabled | Boolean | true | Enable/disable auto-adapt |
safe_threshold | Number | 0.70 | Minimum confidence for auto-apply (0-1) |
safe_types | String[] | ["expand_step", "refine_step", "contract_step"] | Types eligible for auto-apply |
structural_mode | String | "off" | "off" or "safe_delete_only" |
structural_safe_delete_threshold | Number | 0.95 | Minimum confidence for auto-delete |
max_auto_applies_per_baseline | Number | 3 | Max adaptations auto-applied per baseline |
Cannot provide both auto_adapt_config and legacy auto_adapt boolean in same request.
DELETE /api/v1/workflows/{id}
Delete a workflow and stop scheduled patrols.
GET /api/v1/workflows/{id}/details
Get comprehensive workflow info including notification_settings, notification_stats (total_executions, notifications_sent, notifications_suppressed, suppression_rate, last_suppression_reason).
POST /api/v1/workflows/{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 × 100 |
net_new_urls | Enriched data for new URLs (title, snippet, published_date) |
previous_execution_id | Previous execution (null for first) |
content_recency | Recency filtering info (see below) |
First execution counts all URLs as "new". For global uniqueness, use a Session (URL dedup via session_urls table).
Content Recency Filtering
| Field | Description |
|---|---|
recency_window_days | Days used as recency window |
recency_window_source | interval (3x configured) or execution_gap (1.5x actual gap) |
confidence_threshold | Minimum confidence to filter (0-1), configurable via recency_confidence_threshold |
urls_filtered_as_stale | Count of filtered URLs |
filtered_content[] | url, detected_date, confidence, reason |
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).
Result classifications: NEW (relevant), CONTEXT (background), UPDATE (previously reported), IRRELEVANT (filtered).
The LLM summarizer 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).
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.
POST /api/v1/workflows/{id}/retry
Retry a failed workflow execution.
POST /api/v1/workflows/{id}/retry-steps
Retry specific failed steps. Params: step_ids (String[], required), execution_id (String, optional).
POST /api/v1/workflows/{id}/share
Toggle public sharing. Body: {"public_share": true/false}
GET /api/v1/workflows/{id}/timeline
Chronological execution history (last 50). Each includes notification_suppressed_at, suppression_reason, information_gain_score.
GET /api/v1/workflows/{id}/diff
Changes between executions. Query: limit (1-50, default 10), since (ISO timestamp).
Response: stats (change_rate, most_volatile_fields), analytics (trends, ranges), diffs[] (field, from, to, change_type, change_percent), latest.
Change Types: increase, decrease, added, removed, text_change, status_change
GET /api/v1/public/workflow/{id}
View publicly shared workflow (no auth).
GET /api/v1/public/workflow/{id}/timeline
View public workflow timeline (no auth).
GET /api/v1/workflows/webhook-urls
Get webhook URLs configured for workflows.
Notifications
Signal Delivery Intelligence (notification_settings)
| Field | Type | Default | Description |
|---|---|---|---|
suppression_threshold | Number | 30 | Min information gain score (0-100) to deliver a signal. Presets: 0=all, 30=balanced, 50=important, 70=critical |
Email (email_config)
| Field | Type | Description |
|---|---|---|
enabled | Boolean | Enable email notifications |
per_execution | Boolean | Send after each execution |
digest | String | none, daily, weekly |
recipients | Array | Custom emails (max 10) or null for account email |
Slack (slack_config)
| Field | Type | Description |
|---|---|---|
enabled | Boolean | Enable Slack notifications |
webhook_url | String | Slack webhook URL |
channel | String | Override default channel |
per_execution | Boolean | Send after each execution |
event_types | Array | execution.completed, diff.detected, condition.met, execution.failed |
GET /api/v1/workflows/{id}/test-slack
Check Slack configuration status.
POST /api/v1/workflows/{id}/test-slack
Send a test Slack notification. FREE
NL Condition Feedback API
Calibrate natural language stop conditions.
GET /api/v1/workflows/{id}/feedback
Get calibration status.
POST /api/v1/workflows/{id}/feedback
Submit feedback. Actions: confirmed (true positive), dismissed (false positive), manual_stop (false negative), no_action
DELETE /api/v1/workflows/{id}/feedback
Reset calibration data.
Quality Assessments API
Submit answers to quality_questions from workflow endpoints. Stored as training signals, can trigger healing actions. FREE.
POST /api/v1/workflows/{id}/assessments
| Parameter | Type | Required | Description |
|---|---|---|---|
assessments | Array | Yes | 1-10 items with question_id, answer, optional context (500 chars), execution_id |
Answer → Signal: Positive (sufficient, comprehensive_enough, real_event, still_relevant, filter_is_correct, expected_churn) → result_thumbs_up. Negative (insufficient, too_selective, false_alarm, needs_adjustment, too_aggressive, critical, unstable_results, can_pause) → result_thumbs_down + healing. Neutral (not_sure, nice_to_have, irrelevant) → skipped.
Healing Actions: insufficient → 2x max_pages, critical → retry flag, needs_adjustment → query update rec, too_aggressive → +0.1 recency threshold, false_alarm → NL calibration, can_pause → pause workflow, unstable_results → churn investigation.
MCP Integration: Assessments submitted inline on zipfai_get_workflow, zipfai_workflow_timeline, zipfai_workflow_diff, zipfai_workflow_updates.
Execution Feedback API
Thumbs-up/thumbs-down on executions. Stored in workflow_training_signals. FREE.
POST /api/v1/workflows/{id}/executions/{id}/feedback
| Parameter | Type | Required | Description |
|---|---|---|---|
rating | String | Yes | positive or negative |
reason_category | String | Negative: yes | See categories below |
comment | String | No | Max 1000 chars (required when reason_category=other) |
result_url | String | No | Specific result URL |
workflow_step_id | String | No | Step ID for multi-step workflows |
idempotency_key | String | No | Replay-safe key |
actor_model | String | No | MCP actor attribution |
Reason Categories: Positive: relevant_results, accurate_information, timely_alert, good_formatting. Negative: irrelevant_results, missing_information, outdated_content, false_positive, missed_alert, too_slow, other.
Negative false_positive auto-forwards to NL calibration.
Other Execution Feedback Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /{id}/executions/{id}/feedback | Fetch feedback. Query: workflow_step_id, mine, limit |
| DELETE | /{id}/executions/{id}/feedback | Retract your feedback. Query: workflow_step_id |
| GET | /{id}/execution-feedback | List all feedback with cursor pagination. Filters: signal_type, actor_type, reason_category, execution_id, workflow_step_id, since, until, mine |
| GET | /{id}/execution-feedback/stats | Aggregated stats: counts, positive_rate, coverage_rate, by_reason, by_actor_type, trends |
| GET | /{id}/feedback-impact | How feedback shapes behavior. Returns your_ratings, negative_patterns, calibration_impact (NL conditions only). 404 if not owner. |
GET /api/v1/workflows/{id}/executions/{execId}/feedback
Fetch feedback for a specific execution. Query: workflow_step_id, mine, limit.
DELETE /api/v1/workflows/{id}/executions/{execId}/feedback
Retract your feedback. Query: workflow_step_id.
GET /api/v1/workflows/{id}/execution-feedback
List all feedback with cursor pagination. Filters: signal_type, actor_type, reason_category, execution_id, workflow_step_id, since, until, mine.
GET /api/v1/workflows/{id}/execution-feedback/stats
Aggregated stats: counts, positive_rate, coverage_rate, by_reason, by_actor_type, trends.
GET /api/v1/workflows/{id}/feedback-impact
How feedback shapes behavior. Returns your_ratings, negative_patterns, calibration_impact (NL conditions only). 404 if not owner.
POST /api/v1/workflows/{id}/execution-feedback/batch
Batch submit 1-20 items with execution_id, rating, optional fields.
MCP Tools
Feedback via MCP: zipfai_execution_ratings, zipfai_execution_rating_stats, zipfai_feedback_impact. All set X-Zipf-Signal-Source: mcp.
Standalone Feedback API
Rate any signal your agents deliver — search, crawl, or ask results — even outside a workflow context. FREE.
POST /api/v1/feedback
Submit feedback for a standalone search, crawl, or ask job. Params: execution_id (required), rating (positive/negative), reason_category, comment, result_url.
POST /api/v1/feedback/batch
Batch submit 1-20 feedback items with execution_id, rating, and optional fields.
GET /api/v1/feedback/queue
Unrated executions ranked by feedback value. Query: workflow_id, include_standalone, limit.
GET /api/v1/feedback/email
One-click feedback handler for email/Slack notification links. HMAC-verified, no auth required.
Recrawl API
Persistent change detection for high-value pages. See Crawl API for full parameter docs.
GET /api/v1/workflows/{id}/recrawl
Get recrawl configuration and stats.
POST /api/v1/workflows/{id}/recrawl
Enable or update recrawl configuration. Params: strategy, min_interval_hours, max_interval_hours, importance_multiplier, change_detection, priority_threshold, execute_now.
PATCH /api/v1/workflows/{id}/recrawl
Trigger an immediate recrawl.
DELETE /api/v1/workflows/{id}/recrawl
Disable recrawl for this workflow.
Validation API
Pre-flight URL validation with health checks and correction suggestions.
GET /api/v1/workflows/{id}/validate
Get validation status: validation_config, last_validation_at, validation_status (valid/warnings/invalid/unknown), can_validate.
POST /api/v1/workflows/{id}/validate
| Parameter | Default | Description |
|---|---|---|
url_health_check | true | Check URL reachability |
full_validation | true | Validate step references |
force | false | Re-validate even if recent |
Response: validation.status, urls_checked, urls_healthy, urls_failed, failed_urls[], redirect_urls[] (with final_url), suggestions[], step_reference_issues[], quick_fix_available, quick_fix_url.
Auto-detected corrections: www1→www, http→https, .cpm/.comm→.com
Recovery API
Smart recovery for failed URLs using search-based replacement discovery.
GET /api/v1/workflows/{id}/recovery
List pending_suggestions[], recent_suggestions[], available actions.
POST /api/v1/workflows/{id}/recovery
| Parameter | Type | Description |
|---|---|---|
suggestion_ids | Array | Specific suggestions to process |
apply_all | Boolean | Apply all pending |
reject_all | Boolean | Reject all pending |
reject_reason | String | Reason for rejection |
retry_steps | Boolean | Re-execute affected steps (default: true) |
POST /api/v1/workflows/{id}/apply-suggestions
Quick-fix: apply validation suggestions. Params: suggestion_ids (format: step_id:field), apply_all. Without params: applies high-confidence (>=0.9) only.
Baseline Adaptations API
Manage adaptation recommendations from first execution of AI-planned workflows. FREE.
GET /api/v1/workflows/{id}/baseline-adaptations
List recommendations. Query: status (pending/applied/rejected/deferred).
POST /api/v1/workflows/{id}/baseline-adaptations
| Parameter | Type | Required | Description |
|---|---|---|---|
apply | String[] | Yes | IDs to apply (empty [] valid) |
reject | String[] | Yes | IDs to reject (empty [] valid) |
expected_version | Number | Yes | Workflow version from GET response |
reject_reasons | Object | No | Map of ID → reason |
Version mismatch is logged but proceeds. Row-level conflicts return 409. Response: applied_count, rejected_count, new_version, workflow_updated.
Standalone Feedback API
Rate any signal your agents deliver — search, crawl, or ask results — even outside a workflow context. Feedback trains patrol accuracy over time. FREE.
POST /api/v1/feedback
Submit feedback for a standalone search, crawl, or ask job. Params: execution_id (required), rating (positive/negative), reason_category, comment, result_url.
POST /api/v1/feedback/batch
Batch submit 1-20 feedback items with execution_id, rating, and optional fields.
GET /api/v1/feedback/email
One-click feedback handler for email/Slack notification links. HMAC-verified, no auth required.
GET /api/v1/feedback/queue
Unrated executions ranked by feedback value. Query: workflow_id, include_standalone, limit.
MCP Tools
zipfai_workflow_updates — Consolidated patrol digest. Params: since (24h default), format (json/briefing/briefing_llm/compact), include_inactive, max_workflows, verbose. Signal scoring: 0-100 (urgent 70+, notable 40-69, routine 20-39, noise <20).
Other: zipfai_list_workflows, zipfai_get_workflow, zipfai_create_workflow, zipfai_update_workflow, zipfai_execute_workflow, zipfai_workflow_timeline, zipfai_workflow_diff, zipfai_plan_workflow, zipfai_delete_workflow, zipfai_feedback_queue, zipfai_feedback_impact