Back to API Overview

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

ModeDescriptionKey Config
simpleSingle agent patrol per execution (default)workflow_type, operation_config
multi_stepMulti-agent pipeline with dependenciessteps[] array
ai_plannedDescribe what to watch; AI generates the patrol pipelineintent, max_credits_per_execution

Step Types (for multi_step mode)

TypeDescriptionConfig Fields
searchWeb searchquery, max_results, query_decomposition
crawlWeb crawlingurls, max_pages, extraction_schema
aggregateCombine/summarizeaggregation_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.

ParameterTypeDefaultDescription
intentStringrequiredThe monitoring intent to assess (10-2000 chars)
timeoutNumber10000Timeout in milliseconds (1000-30000)

Rate Limit: 10/hour/user

Response:

FieldTypeDescription
assessmentStringspecific or vague
specificity_scoreNumber1-10 (7+ is specific enough)
is_assessedBooleanfalse when assessment_source=fallback (system failure, not a real assessment)
assessment_sourceStringllm (full), heuristic (rate-limited), or fallback (LLM failed, defaults to specific/7)
fallback_reason_codeStringtimeout, parse_error, provider_error, rate_limited (only when source !== llm)
vague_aspectsString[]What's unclear (only if vague)
proposed_intentStringClearer rewrite (only if vague)
what_we_clarifiedString[]What was improved (only if vague)
inferredObjectAdvisory metadata: trigger_conditions, exclusions, entities, source_types, suggested_cadence (hourly/daily/weekly/monthly), monitoring_type, extraction_fields
reasoningStringBrief 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

ParameterTypeDescription
intentString (required)Natural language description (10-2000 chars)
nameStringOptional workflow name
max_credits_per_executionNumberExecution budget limit
planning_budgetNumberPlanner budget hint (takes precedence over max_credits_per_execution)
quality_modeStringquality_first (default) or balanced
skip_entity_discoveryBooleanSkip entity discovery for faster response

Phased Planning Parameters

ParameterTypeDescription
phaseStringdiscover, research, or generate. Omit for full pipeline.
planning_session_idUUIDResume from previous phase. Required for research/generate.
entity_overridesObject{add: [{name, type}], remove: [name]}
research_feedbackStringFree-form guidance (e.g., "focus on enterprise")
source_overridesObject{add: [url], remove: [url]}
generation_overridesObject{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

ParameterTypeRequiredDescription
nameStringYesWorkflow name (max 255 chars)
modeStringNosimple (default), multi_step, ai_planned
stop_conditionObjectYesWhen to complete workflow
recency_confidence_thresholdNumberNoContent recency filter confidence (0-1, default 0.50)
dry_runBooleanNoEstimate 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)

ParameterDescriptionExample
intervalHuman-readable ("N unit": minutes/hours/days/weeks)"6 hours", "1 day"
interval_minutesRaw minutes (takes precedence over interval)60
cron_expression5-field cron"0 9 * * MON,WED,FRI"
scheduled_forOne-time ISO 8601"2025-01-15T15:00:00Z"
anchor_minuteAlign to minute (0-59)0
timezoneIANA timezone (default: UTC)"America/New_York"

Stop Condition Types

TypeDescriptionKey Fields
result_countResult count meets conditionoperator (>,<,>=,<=,==), value
contains_urlResults contain specific URLurl
field_valueField matches valuefield, operator, value
extracted_fieldExtracted crawl field matchesfield, operator, value
natural_languageLLM evaluates conditiondescription, confidence_threshold (default: 0.7)
alwaysNever 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.

FieldTypeDefaultDescription
enabledBooleantrueEnable/disable auto-adapt for this workflow
safe_thresholdNumber0.70Minimum confidence for safe type auto-apply (0-1)
safe_typesString[]["expand_step", "refine_step", "contract_step"]Adaptation types eligible for auto-apply
structural_modeString"off""off" or "safe_delete_only" — controls structural changes (step deletion)
structural_safe_delete_thresholdNumber0.95Minimum confidence for auto-delete (when structural_mode=safe_delete_only)
max_auto_applies_per_baselineNumber3Maximum 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)

FieldTypeDefaultDescription
enabledBooleantrueEnable/disable auto-adapt
safe_thresholdNumber0.70Minimum confidence for auto-apply (0-1)
safe_typesString[]["expand_step", "refine_step", "contract_step"]Types eligible for auto-apply
structural_modeString"off""off" or "safe_delete_only"
structural_safe_delete_thresholdNumber0.95Minimum confidence for auto-delete
max_auto_applies_per_baselineNumber3Max 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:

FieldDescription
net_new_countURLs not in previous execution
dropped_countURLs no longer in results
retained_countURLs in both executions
change_rate(new + dropped) / total_unique × 100
net_new_urlsEnriched data for new URLs (title, snippet, published_date)
previous_execution_idPrevious execution (null for first)
content_recencyRecency 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

FieldDescription
recency_window_daysDays used as recency window
recency_window_sourceinterval (3x configured) or execution_gap (1.5x actual gap)
confidence_thresholdMinimum confidence to filter (0-1), configurable via recency_confidence_threshold
urls_filtered_as_staleCount 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)

FieldTypeDefaultDescription
suppression_thresholdNumber30Min information gain score (0-100) to deliver a signal. Presets: 0=all, 30=balanced, 50=important, 70=critical

Email (email_config)

FieldTypeDescription
enabledBooleanEnable email notifications
per_executionBooleanSend after each execution
digestStringnone, daily, weekly
recipientsArrayCustom emails (max 10) or null for account email

Slack (slack_config)

FieldTypeDescription
enabledBooleanEnable Slack notifications
webhook_urlStringSlack webhook URL
channelStringOverride default channel
per_executionBooleanSend after each execution
event_typesArrayexecution.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

ParameterTypeRequiredDescription
assessmentsArrayYes1-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

ParameterTypeRequiredDescription
ratingStringYespositive or negative
reason_categoryStringNegative: yesSee categories below
commentStringNoMax 1000 chars (required when reason_category=other)
result_urlStringNoSpecific result URL
workflow_step_idStringNoStep ID for multi-step workflows
idempotency_keyStringNoReplay-safe key
actor_modelStringNoMCP 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

MethodEndpointDescription
GET/{id}/executions/{id}/feedbackFetch feedback. Query: workflow_step_id, mine, limit
DELETE/{id}/executions/{id}/feedbackRetract your feedback. Query: workflow_step_id
GET/{id}/execution-feedbackList all feedback with cursor pagination. Filters: signal_type, actor_type, reason_category, execution_id, workflow_step_id, since, until, mine
GET/{id}/execution-feedback/statsAggregated stats: counts, positive_rate, coverage_rate, by_reason, by_actor_type, trends
GET/{id}/feedback-impactHow 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

ParameterDefaultDescription
url_health_checktrueCheck URL reachability
full_validationtrueValidate step references
forcefalseRe-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: www1www, httphttps, .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

ParameterTypeDescription
suggestion_idsArraySpecific suggestions to process
apply_allBooleanApply all pending
reject_allBooleanReject all pending
reject_reasonStringReason for rejection
retry_stepsBooleanRe-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

ParameterTypeRequiredDescription
applyString[]YesIDs to apply (empty [] valid)
rejectString[]YesIDs to reject (empty [] valid)
expected_versionNumberYesWorkflow version from GET response
reject_reasonsObjectNoMap 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

Skip to main content
Workflow API - Zipf AI Documentation