Workflow API

Scheduled recurring operations that run automatically until conditions are met. Perfect for monitoring, alerting, and automated data collection.

Lifecycle: active → paused → completed/failed

Credits: 1 credit/execution (basic) | 2 credits (with NL condition) | Variable for multi-step/AI-planned

Workflow Modes

Step Types (for multi_step mode)

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 to execute reliably. Returns specificity score, identifies vague aspects, and proposes clearer rewrites for vague intents. FREE (no credits charged).

Rate Limit: 10 requests per hour per user

Response:

Assessment Source:

Inferred Metadata:

Example:

curl -X POST https://www.zipf.ai/api/v1/workflows/assess-intent \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"intent": "Tell me when a new LLM releases"}'

Returns assessment: "vague", specificity_score: 3, a proposed_intent rewrite, and inferred metadata (trigger conditions, entities, suggested cadence, etc.).

GET /api/v1/workflows/plan

Get information about workflow planning capabilities.

POST /api/v1/workflows/plan

Preview AI-planned workflow before creating. Supports iterative phased planning (discover → research → generate) or one-shot full pipeline (backward-compatible default).

Credits: Variable based on planning preset — only actually-consumed credits are charged. Preset budgets: quick (~10), standard (~30), thorough (~50), comprehensive (~100). Returns 402 if insufficient credits.

Core Parameters

Phased Planning Parameters

Phased Planning Flow

POST /plan {intent, phase: "discover"}
  → returns entities[], planning_session_id

POST /plan {planning_session_id, phase: "research", entity_overrides?}
  → returns enrichment, classification, planning_results

POST /plan {planning_session_id, phase: "generate", generation_overrides?}
  → returns workflow steps, validation

POST /workflows {planning_session_id, mode: "ai_planned", stop_condition, interval}
  → creates workflow from accumulated session state (no re-planning)

Planning sessions expire after 2 hours. Sessions linked to created workflows are kept permanently.

Phase Response Shape

Each phase response includes: planning_session_id, phase, phase_complete, next_phase, credits.consumed_this_phase, credits.total_consumed.

Full Pipeline Response (phase omitted)

Response includes: planning_profile (precision_linear | dual_lane_hybrid | fork_join_dag), topology_reason, planning_quality_score, planning_overhead_ratio, coverage_score, depth_score, coverage_gaps.

GET /api/v1/workflows/plan/{session_id}

Retrieve the current state of a planning session. Useful for session recovery after disconnect, or inspecting accumulated state between phased planning calls.

Authentication: Bearer token required. Only the session owner can access their sessions.

Response: Returns full session state including current_phase, accumulated phase outputs (entities, enrichment, classification, workflow_definition, reasoning_trace, validation), any overrides applied, credits_consumed, and expires_at (2-hour TTL).

Errors: 400 if session expired, 404 if not found or not owned by caller.

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 (every 15s)

GET /api/v1/workflows

List workflows with pagination.

Query Parameters:

• limit (Int) - Results per page (1-100)
• offset (Int) - Pagination offset
• status (String) - Filter by status: active, paused, completed, failed

GET /api/v1/workflows/analytics

Get aggregate workflow analytics across all workflows the caller can access (owned workflows + optionally org-shared workflows).

Query Parameters:

Response includes: totals (workflows, executions, success rate, credits, tokens, estimated time saved), timing (avg/p50/p95 duration, start/completion adherence), composition (breakdown by mode), series (time-bucketed executions and tokens).

Bucketing: 1d = hourly UTC buckets, 7d/30d = daily UTC buckets, all = monthly UTC buckets.

GET /api/v1/workflows/resume-all

Get counts of workflows paused by reason and documentation for the resume endpoint.

Response includes:

• current_paused_counts - Count of paused workflows by reason (credits_exhausted, subscription_expired, rate_limited)
• total_paused_auto - Total count of auto-paused workflows

POST /api/v1/workflows/resume-all

Resume all workflows that were auto-paused due to a specific reason. Recalculates next_execution_at for each resumed workflow.

Response includes:

• resumed_count - Number of workflows resumed
• workflows[] - Array of resumed workflows with id, name, next_execution_at
• credits.balance_after - Current credit balance
• credits.estimated_cost_next_execution - Rough estimate for next execution cycle
• warning - Warning message if credits are still low

Example:

# Resume all credit-paused workflows
curl -X POST https://www.zipf.ai/api/v1/workflows/resume-all \
  -H "Authorization: Bearer wvr_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pause_reason": "credits_exhausted"}'

POST /api/v1/workflows

Create a new workflow.

Core Parameters

Mode-Specific Parameters

Simple mode: workflow_type (search/crawl), operation_config Multi-step: steps[] array AI-planned: intent, max_credits_per_execution

Schedule Configuration (one required)

Interval formats: interval accepts "N unit" where unit is minutes, hours, days, or weeks (singular or plural). If both interval and interval_minutes are provided, interval_minutes takes precedence.

Stop Condition Types

NL Confidence Guide: High (0.8-0.9) = strong evidence only | 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

DELETE /api/v1/workflows/{id}

Delete a workflow and stop scheduled executions.

GET /api/v1/workflows/{id}/details

Get comprehensive workflow information including stats, configuration, and notification intelligence.

Response includes:

• notification_settings - Suppression configuration (suppression_threshold)
• notification_stats - Suppression metrics:
  • total_executions - Total executions tracked
  • notifications_sent - Notifications delivered
  • notifications_suppressed - Notifications filtered as low-value
  • suppression_rate - Percentage of noise reduction
  • last_suppression_reason - Most recent suppression reason

POST /api/v1/workflows/{id}/execute

Execute workflow immediately. Does not affect regular schedule.

Supports dry_run: true to estimate cost without executing.

Response includes:

• execution.credits - Credits consumed
• execution.condition_met - Whether stop condition triggered
• execution.result_changes - For search: see Result Change Tracking below

Result Change Tracking

For search workflows, each execution compares against the immediately previous execution (not all historical executions):

Note: A URL can be counted as "new" multiple times if it oscillates in/out of search results. The first execution of a workflow counts all URLs as "new" (no baseline for comparison).

For global uniqueness tracking: Use a Session with your workflow. Sessions maintain URL deduplication via the session_urls table, providing true "never seen before" filtering.

Content Recency Filtering

When stale content is filtered from "net new" results, the response includes a content_recency object:

Confidence Threshold Guide:

• 0.90+ (Permissive): Only filter with explicit dates or very clear signals
• 0.70-0.85 (Balanced): Filter when date markers or URL patterns indicate old content
• 0.50 (Default): Filter when we have any reasonable signal of old content
• 0.40 or below (Aggressive): Filter even with lower confidence signals

Intent Relevance Filtering

Execution summaries now include intent-based relevance filtering. The LLM summarizer filters results that don't match your workflow's monitoring intent, preventing irrelevant content from polluting notifications.

How Intent is Extracted (priority order):

1. intent field (AI-planned workflows) - Most explicit
2. description field - User-provided context
3. operation_config.query (simple workflows) - Implicit from search query
4. name field - Last resort fallback (filtering disabled)

When the summarizer has a clear intent, results are classified as:

• NEW - Genuinely new and relevant to monitoring intent
• CONTEXT - Provides background context (not reported as new)
• UPDATE - Updates to previously reported information
• IRRELEVANT - Not related to monitoring intent (filtered)

Response includes (when intent filtering is active):

{
  "workflow_execution_summary": {
    "summary": "...",
    "key_findings": [...],
    "intent_relevance_filter": {
      "filtered_count": 3,
      "filtered_items": [
        {"url": "...", "title": "Winter Storm Warning", "reason": "Weather news, not industrial tenant announcements"}
      ],
      "monitoring_intent_used": "Monitor industrial tenant announcements in Dallas"
    }
  }
}

Notification Suppression: When all changes are filtered as irrelevant (filtered_count > 0 and key_findings is empty), notifications can be suppressed. This prevents "no relevant changes" emails for executions that found new URLs but none matching your intent.

POST /api/v1/workflows/{id}/retry

Retry a failed workflow execution.

POST /api/v1/workflows/{id}/retry-steps

Retry specific failed steps within a workflow execution. Useful for multi-step and AI-planned workflows where only some steps failed.

POST /api/v1/workflows/{id}/share

Toggle public sharing for a workflow. Body: {"public_share": true/false}

GET /api/v1/workflows/{id}/timeline

Get chronological execution history (last 50 executions).

Each execution includes suppression tracking:

• notification_suppressed_at - Timestamp when notification was suppressed (null if sent)
• suppression_reason - Why the notification was suppressed
• information_gain_score - Score (0-100) used for suppression decision

GET /api/v1/workflows/{id}/diff

Get what changed between workflow executions. AI-native diff mode returns changes instead of raw data.

Query Parameters:

• limit (Int) - Number of diffs to return (1-50, default: 10)
• since (String) - Only show diffs after this ISO timestamp

Response includes:

• stats - executions_with_changes, change_rate, most_volatile_fields
• analytics - Field trends, numeric ranges, extraction reliability
• diffs[] - Per-execution changes with field, from, to, change_type, change_percent
• latest - Most recent state with changes summary

Change Types: increase, decrease, added, removed, text_change, status_change

GET /api/v1/public/workflow/{id}

View a publicly shared workflow (no authentication required).

GET /api/v1/public/workflow/{id}/timeline

View public workflow timeline (no authentication required).

GET /api/v1/workflows/webhook-urls

Get webhook URLs configured for workflows.

Notifications

Notification Intelligence (notification_settings)

Controls smart notification suppression to filter low-value "no new developments" notifications.

Threshold Presets:

• 0 - All notifications (no suppression)
• 30 - Balanced (recommended) - filters obvious "no changes" notifications
• 50 - Important only - more aggressive filtering
• 70 - Critical only - only send high-value alerts

Example:

{
  "notification_settings": { "suppression_threshold": 50 },
  "email_config": { "enabled": true, "per_execution": true },
  "slack_config": { "enabled": true, "webhook_url": "..." }
}

Email (email_config)

Slack (slack_config)

GET /api/v1/workflows/{id}/test-slack

Check Slack configuration status for a workflow.

POST /api/v1/workflows/{id}/test-slack

Send a test Slack notification. FREE

Feedback API (NL Conditions)

Calibrate natural language stop conditions over time.

GET /api/v1/workflows/{id}/feedback

Get calibration status for natural language stop condition.

POST /api/v1/workflows/{id}/feedback

Submit feedback on trigger evaluation.

User Actions: confirmed (true positive), dismissed (false positive), manual_stop (false negative), no_action

DELETE /api/v1/workflows/{id}/feedback

Reset calibration data for a workflow.

Quality Assessments API

Submit answers to quality_questions returned by workflow endpoints. Assessments are stored as training signals and can trigger automatic healing actions (e.g., increasing crawl page budgets, adjusting NL condition calibration). FREE (no credits charged).

POST /api/v1/workflows/{id}/assessments

Submit quality question assessments for a workflow.

Answer Classification:

Healing Actions (triggered by negative assessments):

Response: Returns assessments_processed, stored, skipped, failed counts, per-item results[] with status, and healing_actions[] with action type and details.

MCP Integration: Assessments can be submitted inline as a side-parameter on zipfai_get_workflow, zipfai_workflow_timeline, zipfai_workflow_diff, and zipfai_workflow_updates — no separate tool call needed. MCP responses include assessment_submission results and quality_loop guidance with recommended_chain.

Execution Feedback API

Thumbs-up/thumbs-down feedback on workflow executions. Signals are stored in the workflow_training_signals table as part of the RL feedback loop. FREE (no credits charged).

POST /api/v1/workflows/{id}/executions/{id}/feedback

Submit feedback for a specific execution.

Reason Categories:

Response: Returns status (created, updated, or idempotent_replay) and feedback object with signal details including actor, signal_type, immediate_reward, and created_at.

NL Calibration: Negative feedback with false_positive reason automatically forwards to NL stop condition calibration.

GET /api/v1/workflows/{id}/executions/{id}/feedback

Fetch feedback for a specific execution.

Query Parameters:

• workflow_step_id (String) - Filter by step ID
• mine (Bool) - Only return feedback from the authenticated actor
• limit (Int) - Results per page (1-100, default: 50)

DELETE /api/v1/workflows/{id}/executions/{id}/feedback

Retract your feedback for an execution. Only deletes feedback matching the authenticated actor's identity.

Query Parameters: workflow_step_id (String) - Target specific step feedback.

Response: Returns retracted: true and deleted_count.

GET /api/v1/workflows/{id}/execution-feedback

List all feedback for a workflow with cursor pagination and filtering.

Query Parameters:

Response includes: feedback[], pagination.limit, pagination.next_cursor

GET /api/v1/workflows/{id}/execution-feedback/stats

Aggregated feedback statistics for a workflow.

Response: Returns total_feedback, thumbs_up_count, thumbs_down_count, positive_rate, feedback_coverage_rate, breakdowns by_reason and by_actor_type, trends (7d/30d), and total_immediate_reward.

GET /api/v1/workflows/{id}/feedback-impact

Show how submitted feedback is shaping workflow behavior and calibration. Requires ownership of the workflow — returns 404 if the workflow does not exist or the requesting customer does not own it.

Response: Returns your_ratings (total, positive, negative, coverage_rate), negative_patterns (top reasons, recommended edits), and community stats.

calibration_impact is null unless the workflow uses a natural_language stop condition with calibration data. When populated, includes nl_condition_adjustments, false_positive_reports, and current/original confidence thresholds.

Errors: 404 if workflow not found or not owned by the requesting customer.

POST /api/v1/workflows/{id}/execution-feedback/batch

Submit feedback for multiple executions in a single request.

Response: Always HTTP 200 with submitted, succeeded, failed counts and per-item results[] with status.

MCP Tools

Feedback and assessments are available via MCP: zipfai_get_workflow, zipfai_workflow_timeline, zipfai_workflow_diff, zipfai_workflow_updates (all accept inline assessments[]), zipfai_execution_ratings, zipfai_execution_rating_stats, zipfai_feedback_impact. All set X-Zipf-Signal-Source: mcp for actor attribution.

Recrawl API

Importance-based recrawl prioritization. Requires session with Smart Crawl.

GET /api/v1/workflows/{id}/recrawl

Get recrawl configuration and stats.

POST /api/v1/workflows/{id}/recrawl

Enable or update recrawl configuration.

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, step reference validation, and URL correction suggestions.

GET /api/v1/workflows/{id}/validate

Get validation status and configuration for a workflow.

Response includes:

• validation_config - Current validation settings
• last_validation_at - Timestamp of last validation
• validation_status - valid, warnings, invalid, unknown
• can_validate - Whether workflow supports validation (multi_step/ai_planned only)

POST /api/v1/workflows/{id}/validate

Run validation checks on workflow URLs and step references.

Response includes:

• validation.status - valid, warnings, invalid
• validation.urls_checked, urls_healthy, urls_failed
• validation.failed_urls[] - URLs that returned errors
• validation.redirect_urls[] - URLs with redirects (includes final_url)
• validation.suggestions[] - URL correction suggestions
• validation.step_reference_issues[] - Invalid step references
• quick_fix_available - Whether auto-corrections are available
• quick_fix_url - Endpoint to apply suggestions

URL Corrections Detected:

• www1 → www (common typo)
• http → https (protocol upgrade)
• .cpm, .comm → .com (TLD typos)

Recovery API

Smart recovery for failed URLs using search-based replacement discovery.

GET /api/v1/workflows/{id}/recovery

List pending recovery suggestions for a workflow.

Response includes:

• pending_suggestions[] - Suggestions awaiting approval
• recent_suggestions[] - Recently applied/rejected suggestions
• actions - Available action endpoints

POST /api/v1/workflows/{id}/recovery

Apply or reject recovery suggestions.

Response includes:

• applied_count, rejected_count, failed_count
• applied[], rejected[], failed[] - Suggestion IDs by outcome
• retry_steps_triggered - Whether step retry was initiated

POST /api/v1/workflows/{id}/apply-suggestions

Quick-fix endpoint to apply validation suggestions.

Without parameters: Applies only high-confidence suggestions (>=0.9).

Response includes:

• applied_count - Number of suggestions applied
• applied_suggestions[] - Details of applied corrections
• workflow_version - New workflow version after update

MCP Tools

zipfai_workflow_updates (recommended) — Consolidated digest of all workflow updates. Params: since (default 24h), 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 tools: 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

Standalone Feedback API

Rate any Zipf result — not just workflow executions. Search jobs, crawl jobs, and ask jobs can all receive feedback without a workflow context.

Credits: FREE (no credits charged)

POST /api/v1/feedback

Submit feedback for a standalone search, crawl, or ask job.

Response: Same schema as workflow execution feedback.

Ownership: The execution must belong to the authenticated user. Ownership is verified by checking customer_id in the relevant table (search_jobs, crawls, or ask_jobs).

GET /api/v1/feedback/queue

Get unrated executions ranked by feedback value. Returns items most worth rating.

Query Parameters:

Items are ranked by priority signals (stop condition triggered, has changes, NL condition, low coverage, recency). Each item includes execution_id, score, score_reasons, and a feedback_hint with the MCP tool call template.

Response: Returns items[] ranked by feedback value and total_unrated count.

POST /api/v1/feedback/batch

Submit feedback for multiple standalone executions in a single request.

Response: Same schema as workflow batch feedback.

GET /api/v1/feedback/email

One-click feedback handler for email and Slack notification links. Verifies an HMAC-SHA256 signature, submits the feedback, and redirects the user to a thank-you page.

Authentication: None (HMAC token in query string replaces Bearer auth).

Query Parameters:

Behavior:

• Resolves customer_id from the execution via the relevant table
• Verifies the HMAC token (signed with NEXTAUTH_SECRET)
• Submits feedback with actor.type: "human" and actor.source: "api"
• Positive rating redirects to /feedback?status=thanks
• Negative rating redirects to /feedback?status=reason with params for reason selection

Idempotency: Uses execution_id:rating as the idempotency key.

Baseline Adaptations API

View and manage baseline adaptation recommendations generated during the first execution of an AI-planned workflow.

Credits: FREE

GET /api/v1/workflows/{id}/baseline-adaptations

List baseline adaptation recommendations for a workflow.

Query Parameters:

• status (String) - Filter by status: pending, applied, rejected, deferred

POST /api/v1/workflows/{id}/baseline-adaptations

Apply or reject baseline adaptation recommendations in batch. Uses optimistic concurrency via expected_version.

Both apply and reject are required keys but may be empty arrays. At least one must contain IDs for the request to have effect. When an empty array is supplied for either field, the corresponding applied_count or rejected_count in the response will be 0.

Concurrency: If expected_version doesn't match, the server logs the mismatch but proceeds. True concurrent row-level conflicts return 409.

Response: Returns applied_count, rejected_count, new_version, workflow_updated, and optionally skipped_count/skipped_ids for already-processed recommendations.

See Also

• Search API | Crawl API | Sessions API | Common Topics