Newscatcher CatchAll API

[
  {
    "name": "submit_query",
    "description": "Create a new CatchAll processing job from a natural-language query.\n\nUse when:\n- You want to start a new CatchAll web research run from a user query.\n- You want the API to fetch/process sources and then return structured results.\n\nDo not use when:\n- You want status for an existing job (use `get_job_status`).\n- You want records for an existing job (use `pull_results`).\n\nKey rules:\n- `query` is required.\n- You can submit with only `query`; omitted optional fields (`validators`, `enrichments`, `sta"
  },
  {
    "name": "initialize_query",
    "description": "Preview suggested validators, enrichments, and date ranges before submitting.\n\nUse when:\n- You want to inspect/edit auto-generated validators/enrichments before submitting.\n- You want to preview date adjustments via `date_modification_message`.\n\nDo not use when:\n- You want to start processing immediately with final inputs (use `submit_query`).\n\nKey behavior:\n- Preview-only endpoint: does not create a job and does not start processing.\n- Suggestions are LLM-generated and not deterministic across "
  },
  {
    "name": "get_job_status",
    "description": "Check the status of a submitted job.\n\nCall this after submit_query to see if your job is ready.\nStatus progression: submitted -> analyzing -> fetching -> clustering -> enriching -> completed/failed\n\nIMPORTANT: Jobs take several minutes to process.\nFirst check after ~1-2 minutes, then poll every 30-60 seconds.\nBroad searches can take 10-30+ minutes; for long jobs, poll every 60-120 seconds.\nDo NOT call this tool in a tight loop.\nStop polling when status is `completed` or `failed`.\nTreat `submitte"
  },
  {
    "name": "pull_results",
    "description": "Retrieve the results of a job.\n\nCan be called before completion for partial results, or after completion\nfor the full set. Returns clustered, validated, and enriched web results.\nWhile job status is active, call this repeatedly (typically page=1) to\nrefresh partial output. When job reaches completed, iterate all pages.\nIf job fails, call once more to capture any partial output."
  },
  {
    "name": "pull_job_csv",
    "description": "Download a job's results as a CSV file.\n\nUse when:\n- You want the full job output as a CSV for offline analysis or export.\n- Prefer this over `pull_results` when the consumer needs spreadsheet/CSV format."
  },
  {
    "name": "continue_job",
    "description": "Expand a job by processing more records beyond the initial limit.\n\nThis increases the number of records the system processes (which costs\nadditional credits). Only use this when the user wants MORE data processed.\n\nThis only applies to jobs originally submitted with `limit`.\nIf a job was submitted without `limit`, there is nothing to continue.\nThe new_limit must be greater than the previous limit when provided.\nIf omitted, API defaults to your plan maximum."
  },
  {
    "name": "list_user_jobs",
    "description": "List all jobs submitted by you.\n\nReturns your job history with IDs, queries, statuses, and timestamps."
  },
  {
    "name": "delete_job",
    "description": "Permanently delete a job and its results.\n\nUse when:\n- You want to remove a job you no longer need from your account."
  },
  {
    "name": "validate_query",
    "description": "Check the quality of a query before submitting a job (\"Check Query Quality\").\n\nUse when:\n- You want quick feedback on whether a query is well-formed for CatchAll\n  before spending credits on a job.\n- You want concrete suggestions to improve a vague or overly broad query.\n\nDo not use when:\n- You want to preview auto-generated validators/enrichments (use `initialize_query`).\n- You want to actually run a search (use `submit_query`)."
  },
  {
    "name": "create_monitor",
    "description": "Create a recurring monitor from a completed job.\n\nMonitors re-run a job's query on a schedule. Use the explore -> refine -> automate\npattern: submit a job, refine until results match, then create a monitor.\n\nThe schedule is defined in natural language (e.g., 'every day at 9 AM EST').\nAlways include a timezone (in the schedule text or via the `timezone` arg).\nAPI-enforced constraints apply:\n- If `backfill=true`, reference job end_date must be within the last 7 days\n- If `backfill=false`, referenc"
  },
  {
    "name": "list_monitors",
    "description": "List all your monitors.\n\nReturns all monitors with their schedule, status, reference query, and webhook config."
  },
  {
    "name": "pull_monitor_results",
    "description": "Retrieve the latest results from a monitor.\n\nReturns the most recent run's results including run_info, records, and all_records."
  },
  {
    "name": "pull_monitor_csv",
    "description": "Download the latest monitor run's results as a CSV file.\n\nUse when:\n- You want the most recent monitor run output as a CSV for offline analysis or export.\n- Prefer this over `pull_monitor_results` when the consumer needs spreadsheet/CSV format."
  },
  {
    "name": "list_monitor_jobs",
    "description": "List all jobs spawned by a monitor.\n\nReturns the history of scheduled runs for a monitor."
  },
  {
    "name": "disable_monitor",
    "description": "Disable a monitor to stop its scheduled runs.\n\nThe monitor can be re-enabled later with enable_monitor."
  },
  {
    "name": "enable_monitor",
    "description": "Enable a previously disabled monitor to resume its scheduled runs."
  },
  {
    "name": "update_monitor",
    "description": "Update a monitor's webhook assignments and per-run limit.\n\nNote: schedule and reference_job_id cannot be modified through this endpoint.\nWebhooks are centralized — pass webhook IDs (from `create_webhook`/`list_webhooks`)."
  },
  {
    "name": "delete_monitor",
    "description": "Permanently delete a monitor and stop its scheduled runs.\n\nUse when:\n- You want to remove a monitor entirely (use `disable_monitor` to only pause it)."
  },
  {
    "name": "get_monitor_status",
    "description": "Get the status history of a monitor.\n\nUse when:\n- You want to see the timeline of a monitor's state changes (e.g. active,\n  disabled, errored) and any related details."
  },
  {
    "name": "list_webhooks",
    "description": "List all your webhooks.\n\nUse when:\n- You want to see all webhook endpoints configured in your account.\n- You need to find a webhook_id to pass to monitors (via webhook_ids) or jobs."
  },
  {
    "name": "create_webhook",
    "description": "Create a new webhook endpoint.\n\nUse when:\n- You want to register a URL to receive job or monitor result deliveries.\n- You need a webhook_id to attach to a monitor (via webhook_ids) or a job submission.\n- You want the webhook associated with a project from the start (pass `project_id`)."
  },
  {
    "name": "get_webhook",
    "description": "Retrieve the full configuration of a specific webhook.\n\nUse when:\n- You want to inspect a webhook's URL, method, headers, or status by its ID."
  },
  {
    "name": "update_webhook",
    "description": "Update an existing webhook's configuration.\n\nUse when:\n- You want to change a webhook's URL, method, headers, or other settings.\n- You want to enable or disable a webhook (set `is_active`).\n- Only the fields you provide are updated; omitted fields remain unchanged."
  },
  {
    "name": "delete_webhook",
    "description": "Permanently delete a webhook endpoint.\n\nUse when:\n- You want to remove a webhook from your account."
  },
  {
    "name": "test_webhook",
    "description": "Send a test delivery to a webhook endpoint.\n\nUse when:\n- You want to verify a webhook URL is reachable and correctly configured\n  before attaching it to a monitor or job."
  }
]