CatchAll

Official60 toolsLive

by Newscatcher · Python

Web search API: find every relevant event across the open web, not just the top results.

A Web search API MCP server that consolidates open-web events across the entire web, not limited to top results. It exposes a hosted MCP interface for catching all relevant items via NewsCatcher infrastructure and supports integration through a provided URL and API key workflow.

🛠️ Key Features

Web search MCP server for CatchAll
Broad event discovery across the open web
Hosted MCP option; no local deployment required
API key secured access
Quick start with hosted URL and example JSON config
Tool count: 60

🚀 Use Cases

Broad web event discovery beyond top results
News, media, and event monitoring via MCP
Integration with existing NewsCatcher workflows
Rapid testing through hosted endpoints

⚡ Developer Benefits

Minimal setup; hosted MCP avoids cloning and running locally
Clear Quick Start instructions and example config
JSON config example for mcpServers mapping
Documentation excerpts available via readmeExcerpt

⚠️ Limitations

Details focus on hosted usage; local deployment instructions are not included
Readme excerpt indicates reliance on NewsCatcher hosted instance for operation

Captured live from the server via tools/list.

submit_query

Create a new CatchAll processing job from a natural-language query. Use when: - You want to start a new CatchAll web research run from a user query. - You want the API to fetch/process sources and then return structured results. Do not use when: - You want status for an existing job (use `get_job_status`). - You want records for an existing job (use `pull_results`). Key rules: - `query` is required. - You can submit with only `query`; omitted optional fields (`validators`, `enrichments`, `start_date`, `end_date`) are auto-selected/generated by the API. - Optional fields are independent: you can pass any subset (for example, custom `validators` but no `enrichments`), and omitted fields are still auto-selected/generated. - When `connected_dataset_ids` is set, the `query` must describe the **topic or event type only** (e.g. "M&A activity", "regulatory filings", "executive changes"). Do NOT write things like "for my companies", "for the selected list of companies", or "news about my watchlist" — the entity filtering is applied automatically by the connected dataset. Mentioning companies in the query when a dataset is attached is redundant and degrades retrieval quality. - When `connected_dataset_ids` is set, entity-relevance validators (e.g. `company_is_primary_subject`) are generated automatically by the API. Do NOT add them manually to `validators` — they are redundant and may conflict with the auto-generated ones. Only pass validators that describe the **event or topic**, not entity filtering. - `start_date` and `end_date` filter by web page discovery date, not event date. - Discovery dates and extracted event dates can differ. For event-time accuracy, use event-focused validators/enrichments and verify `event_date` in pulled results. - `end_date` must be after `start_date`. - Dates outside your plan lookback limits return API 400. - `limit` controls processed record count (cost-affecting). Omit it to retrieve everything up to your plan's maximum. If provided, must be >= 10. - `validators` / `enrichments` may be passed either as arrays or as JSON-string arrays (for client compatibility). - `validators[].type` must be `boolean` (if omitted, it defaults to `boolean`). - `enrichments[].type` supported values: text, number, date, option, url, company. Basic examples: - validators: `[{"name":"is_acquisition_event","description":"true if page describes an acquisition","type":"boolean"}]` - enrichments: `[{"name":"acquiring_company","description":"Extract acquiring company","type":"company"},{"name":"deal_value","description":"Extract announced deal value","type":"number"}]` Next step: - Save the returned `job_id`. - Poll `get_job_status` and call `pull_results` (partial results can appear before completion).

Parameters16

query	string	required	Plain text search intent (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
context	string	optional	Optional guidance on what to prioritize (for example, target entities, event types, and specific data points you want captured in enrichments). If a company dataset will be attached, note that entity-relevance validators (e.g. `company_is_primary_subject`) will be auto-generated — do not ask for them here. Do not mention things like "company list will be attached".
limit	any	optional	Optional processing cap (minimum 10); affects cost. Omit to retrieve everything up to your plan's maximum.
start_date	string	optional	Optional ISO 8601 UTC start of search window.
end_date	string	optional	Optional ISO 8601 UTC end of search window.
validators	any	optional	Optional custom boolean validators (`name`, `description`, `type`), as array or JSON-string array. When `connected_dataset_ids` is set, do NOT include entity-relevance validators such as `company_is_primary_subject` — the API generates those automatically. Only add validators that describe the event or topic (e.g. `is_acquisition_event`).
enrichments	any	optional	Optional custom enrichments (`name`, `description`, `type`), as array or JSON-string array.
mode	string	optional	Optional job processing mode: `"lite"` (faster, lower cost, less detail) or `"base"` (default, full extraction). If omitted, the API defaults to `"base"`.
project_id	string	optional	Optional project ID to associate this job with.
webhook_ids	any	optional	Optional list of webhook IDs to notify when the job completes (max 5 per job). Use `list_webhooks` / `create_webhook` to get IDs.
schema	string	optional	Optional advanced custom JSON schema string that overrides the default extraction schema. Use `initialize_query` to discover a suitable schema.
connected_dataset_ids	any	optional	Optional list of dataset IDs whose entities narrow the retrieval scope. When set: (1) entity filtering is applied automatically — do NOT mention the company list or watchlist in `query`; (2) entity-relevance validators such as `company_is_primary_subject` are generated automatically — do NOT add them to `validators`. `ed_score_min` defaults to 2 if not provided.
ed_score_min	any	optional	Optional minimum entity-domain relevance score (1-10). Only relevant when `connected_dataset_ids` is set.
ed_association_type	string	optional	Optional filter on how strongly a watchlist entity must appear in each event. Only relevant when `connected_dataset_ids` is set. - `"event_associated"`: keep only events where the entity is a direct actor (default when connected_dataset_ids is set). - `"mention"`: keep all even where the entity is merely referenced.
fetch_all_watchlist_news	boolean	optional	When `True`, retrieves all news for connected watchlist entities without applying topic filtering from `query`. Requires `connected_dataset_ids` to be set. Default: `False`.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Plain text search intent (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "context": {
      "default": "",
      "type": "string",
      "description": "Optional guidance on what to prioritize (for example, target entities,\nevent types, and specific data points you want captured in enrichments).\nIf a company dataset will be attached, note that entity-relevance\nvalidators (e.g. `company_is_primary_subject`) will be auto-generated —\ndo not ask for them here. Do not mention things like \"company list will be attached\"."
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional processing cap (minimum 10); affects cost. Omit to retrieve everything\nup to your plan's maximum."
    },
    "start_date": {
      "default": "",
      "type": "string",
      "description": "Optional ISO 8601 UTC start of search window."
    },
    "end_date": {
      "default": "",
      "type": "string",
      "description": "Optional ISO 8601 UTC end of search window."
    },
    "validators": {
      "anyOf": [
        {
          "items": {
            "description": "Schema for a custom validator.",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "type": {
                "const": "boolean",
                "type": "string"
              }
            },
            "required": [
              "name",
              "description",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional custom boolean validators (`name`, `description`, `type`), as array or JSON-string array.\nWhen `connected_dataset_ids` is set, do NOT include entity-relevance validators such as\n`company_is_primary_subject` — the API generates those automatically. Only add validators\nthat describe the event or topic (e.g. `is_acquisition_event`)."
    },
    "enrichments": {
      "anyOf": [
        {
          "items": {
            "description": "Schema for a custom enrichment.",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "type": {
                "enum": [
                  "text",
                  "number",
                  "date",
                  "option",
                  "url",
                  "company"
                ],
                "type": "string"
              }
            },
            "required": [
              "name",
              "description",
              "type"
            ],
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional custom enrichments (`name`, `description`, `type`), as array or JSON-string array."
    },
    "mode": {
      "default": "",
      "type": "string",
      "description": "Optional job processing mode: `\"lite\"` (faster, lower cost, less detail) or `\"base\"` (default,\nfull extraction). If omitted, the API defaults to `\"base\"`."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional project ID to associate this job with."
    },
    "webhook_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of webhook IDs to notify when the job completes (max 5 per job).\nUse `list_webhooks` / `create_webhook` to get IDs."
    },
    "schema": {
      "default": "",
      "type": "string",
      "description": "Optional advanced custom JSON schema string that overrides the default extraction\nschema. Use `initialize_query` to discover a suitable schema."
    },
    "connected_dataset_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of dataset IDs whose entities narrow the retrieval\nscope. When set: (1) entity filtering is applied automatically — do NOT mention the\ncompany list or watchlist in `query`; (2) entity-relevance validators such as\n`company_is_primary_subject` are generated automatically — do NOT add them to\n`validators`. `ed_score_min` defaults to 2 if not provided."
    },
    "ed_score_min": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional minimum entity-domain relevance score (1-10). Only relevant when\n`connected_dataset_ids` is set."
    },
    "ed_association_type": {
      "default": "",
      "type": "string",
      "description": "Optional filter on how strongly a watchlist entity must appear in\neach event. Only relevant when `connected_dataset_ids` is set.\n- `\"event_associated\"`: keep only events where the entity is a **direct actor** (default when connected_dataset_ids is set).\n- `\"mention\"`: keep all even where the entity is **merely referenced**."
    },
    "fetch_all_watchlist_news": {
      "default": false,
      "type": "boolean",
      "description": "When `True`, retrieves **all** news for connected watchlist\nentities without applying topic filtering from `query`. Requires\n`connected_dataset_ids` to be set. Default: `False`."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

initialize_query

Preview suggested validators, enrichments, and date ranges before submitting. Use when: - You want to inspect/edit auto-generated validators/enrichments before submitting. - You want to preview date adjustments via `date_modification_message`. Do not use when: - You want to start processing immediately with final inputs (use `submit_query`). Key behavior: - Preview-only endpoint: does not create a job and does not start processing. - Suggestions are LLM-generated and not deterministic across calls. - To reuse suggestions, pass them explicitly to `submit_query`.

Parameters4

query	string	required	Natural language query to preview (required). If you plan to attach a company dataset via `connected_dataset_ids` in the subsequent `submit_query`, do NOT reference the company list here — entity filtering is applied automatically by the dataset, not by the query text.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
context	string	optional	Optional guidance on what to prioritize so suggested validators, enrichments, and dates align with your target data points. If a company dataset will be attached in `submit_query`, note that entity-relevance validators (e.g. `company_is_primary_subject`) will be auto-generated — do not ask for them here. Do not mention things like "company list will be attached". Focus on the event or topic only.
fetch_all_watchlist_news	boolean	optional	When `True`, signals that the subsequent job will retrieve all news for connected watchlist entities without topic filtering. Pass this when you intend to use `fetch_all_watchlist_news=True` in `submit_query` so the previewed validators/enrichments are generated accordingly. Requires `connected_dataset_ids` to be set in `submit_query`. Default: `False`.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Natural language query to preview (required). If you plan to attach a\ncompany dataset via `connected_dataset_ids` in the subsequent `submit_query`,\ndo NOT reference the company list here — entity filtering is applied\nautomatically by the dataset, not by the query text."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "context": {
      "default": "",
      "type": "string",
      "description": "Optional guidance on what to prioritize so suggested validators,\nenrichments, and dates align with your target data points. If a company\ndataset will be attached in `submit_query`, note that entity-relevance\nvalidators (e.g. `company_is_primary_subject`) will be auto-generated —\ndo not ask for them here. Do not mention things like \"company list will be attached\".\nFocus on the event or topic only."
    },
    "fetch_all_watchlist_news": {
      "default": false,
      "type": "boolean",
      "description": "When `True`, signals that the subsequent job will\nretrieve all news for connected watchlist entities without topic filtering.\nPass this when you intend to use `fetch_all_watchlist_news=True` in\n`submit_query` so the previewed validators/enrichments are generated\naccordingly. Requires `connected_dataset_ids` to be set in `submit_query`.\nDefault: `False`."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

get_job_status

Check the status of a submitted job. Call this after submit_query to see if your job is ready. Status progression: submitted -> analyzing -> fetching -> clustering -> enriching -> completed/failed IMPORTANT: Jobs take several minutes to process. First check after ~1-2 minutes, then poll every 30-60 seconds. Broad searches can take 10-30+ minutes; for long jobs, poll every 60-120 seconds. Do NOT call this tool in a tight loop. Stop polling when status is `completed` or `failed`. Treat `submitted`, `analyzing`, `fetching`, `clustering`, and `enriching` as active states and continue polling. You don't need to wait for completion to pull results. Partial results are available during `enriching` — call pull_results after ~2 minutes, then poll status every 30-60 seconds and pull again for fresher results. Do not stop pulling just because an intermediate pull is empty/unchanged. Use `progress_validated` vs `candidate_records` to track whether more results may still appear (`progress_validated < candidate_records`). If transport/session fails, resume using the same `job_id`.

Parameters2

job_id	string	required	The job ID returned from submit_query
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job ID returned from submit_query"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

pull_results

Retrieve the results of a job. Can be called before completion for partial results, or after completion for the full set. Returns clustered, validated, and enriched web results. While job status is active, call this repeatedly (typically page=1) to refresh partial output. When job reaches completed, iterate all pages. If job fails, call once more to capture any partial output.

Parameters4

job_id	string	required	The job ID returned from submit_query
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1). Use total_pages from the response to iterate through all results.
page_size	integer	optional	Number of records returned per page (default: 100, max: 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job ID returned from submit_query"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1). Use total_pages from the response to iterate through all results."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of records returned per page (default: 100, max: 1000)."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

pull_job_csv

Download a job's results as a CSV file. Use when: - You want the full job output as a CSV for offline analysis or export. - Prefer this over `pull_results` when the consumer needs spreadsheet/CSV format.

Parameters2

job_id	string	required	The job ID to download as CSV.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job ID to download as CSV."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

continue_job

Expand a job by processing more records beyond the initial limit. This increases the number of records the system processes (which costs additional credits). Only use this when the user wants MORE data processed. This only applies to jobs originally submitted with `limit`. If a job was submitted without `limit`, there is nothing to continue. The new_limit must be greater than the previous limit when provided. If omitted, API defaults to your plan maximum.

Parameters3

job_id	string	required	The job ID to continue processing
new_limit	any	optional	Optional new record processing limit (must exceed the previous limit if provided).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job ID to continue processing"
    },
    "new_limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new record processing limit (must exceed the previous limit if provided)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

list_user_jobs

List all jobs submitted by you. Returns your job history with IDs, queries, statuses, and timestamps.

Parameters6

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1)
page_size	integer	optional	Number of results per page (default: 100, max: 1000)
search	string	optional	Optional text filter on the job query.
ownership	string	optional	Optional ownership filter: 'all', 'own', or 'shared'.
project_id	string	optional	Optional filter to jobs belonging to a specific project.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)"
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)"
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on the job query."
    },
    "ownership": {
      "default": "",
      "type": "string",
      "description": "Optional ownership filter: 'all', 'own', or 'shared'."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional filter to jobs belonging to a specific project."
    }
  },
  "additionalProperties": false
}

delete_job

Permanently delete a job and its results. Use when: - You want to remove a job you no longer need from your account.

Parameters2

job_id	string	required	The job ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}

validate_query

Check the quality of a query before submitting a job ("Check Query Quality"). Use when: - You want quick feedback on whether a query is well-formed for CatchAll before spending credits on a job. - You want concrete suggestions to improve a vague or overly broad query. Do not use when: - You want to preview auto-generated validators/enrichments (use `initialize_query`). - You want to actually run a search (use `submit_query`).

Parameters2

query	string	required	The natural-language query to assess (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The natural-language query to assess (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

create_monitor

Create a recurring monitor from a completed job. Monitors re-run a job's query on a schedule. Use the explore -> refine -> automate pattern: submit a job, refine until results match, then create a monitor. The schedule is defined in natural language (e.g., 'every day at 9 AM EST'). Always include a timezone (in the schedule text or via the `timezone` arg). API-enforced constraints apply: - If `backfill=true`, reference job end_date must be within the last 7 days - If `backfill=false`, reference job age does not matter - Minimum schedule frequency depends on your plan Webhooks are now centralized: register them with `create_webhook`, then pass their IDs here via `webhook_ids` (there is no inline webhook config anymore).

Parameters8

reference_job_id	string	required	ID of a completed job to use as the template
schedule	string	required	Natural language schedule (e.g., 'every day at 9 AM EST', 'every Monday at 8 AM UTC', 'every 48 hours')
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
timezone	string	optional	Optional IANA timezone for the schedule (e.g. 'America/New_York'). Defaults to UTC. A timezone written into the schedule text overrides this.
webhook_ids	any	optional	Optional list of webhook IDs to notify on each run completion (max 5).
limit	any	optional	Optional max records per run (minimum 10). If omitted, API uses plan default.
backfill	boolean	optional	Optional gap-fill toggle before first run (default true).
project_id	string	optional	Optional project ID to associate this monitor with.

Raw schema

{
  "type": "object",
  "properties": {
    "reference_job_id": {
      "type": "string",
      "description": "ID of a completed job to use as the template"
    },
    "schedule": {
      "type": "string",
      "description": "Natural language schedule (e.g., 'every day at 9 AM EST', 'every Monday at 8 AM UTC', 'every 48 hours')"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "timezone": {
      "default": "",
      "type": "string",
      "description": "Optional IANA timezone for the schedule (e.g. 'America/New_York').\nDefaults to UTC. A timezone written into the schedule text overrides this."
    },
    "webhook_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of webhook IDs to notify on each run completion (max 5)."
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional max records per run (minimum 10). If omitted, API uses plan default."
    },
    "backfill": {
      "default": true,
      "type": "boolean",
      "description": "Optional gap-fill toggle before first run (default true)."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional project ID to associate this monitor with."
    }
  },
  "required": [
    "reference_job_id",
    "schedule"
  ],
  "additionalProperties": false
}

list_monitors

List all your monitors. Returns all monitors with their schedule, status, reference query, and webhook config.

Parameters6

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).
search	string	optional	Optional text filter on the monitor query.
ownership	string	optional	Optional ownership filter: 'all', 'own', or 'shared'.
project_id	string	optional	Optional filter to monitors belonging to a specific project.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on the monitor query."
    },
    "ownership": {
      "default": "",
      "type": "string",
      "description": "Optional ownership filter: 'all', 'own', or 'shared'."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional filter to monitors belonging to a specific project."
    }
  },
  "additionalProperties": false
}

pull_monitor_results

Retrieve the latest results from a monitor. Returns the most recent run's results including run_info, records, and all_records.

Parameters2

monitor_id	string	required	The monitor ID to pull results from
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to pull results from"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

pull_monitor_csv

Download the latest monitor run's results as a CSV file. Use when: - You want the most recent monitor run output as a CSV for offline analysis or export. - Prefer this over `pull_monitor_results` when the consumer needs spreadsheet/CSV format.

Parameters2

monitor_id	string	required	The monitor ID to download results for.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to download results for."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

list_monitor_jobs

List all jobs spawned by a monitor. Returns the history of scheduled runs for a monitor.

Parameters3

monitor_id	string	required	The monitor ID to list jobs for
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
sort	string	optional	Sort order by start_date: 'asc' (default) or 'desc'

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to list jobs for"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "sort": {
      "default": "asc",
      "type": "string",
      "description": "Sort order by start_date: 'asc' (default) or 'desc'"
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

disable_monitor

Disable a monitor to stop its scheduled runs. The monitor can be re-enabled later with enable_monitor.

Parameters2

monitor_id	string	required	The monitor ID to disable
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to disable"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

enable_monitor

Enable a previously disabled monitor to resume its scheduled runs.

Parameters3

monitor_id	string	required	The monitor ID to enable
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
backfill	any	optional	Optional backfill behavior for resume.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to enable"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "backfill": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional backfill behavior for resume."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

update_monitor

Update a monitor's webhook assignments and per-run limit. Note: schedule and reference_job_id cannot be modified through this endpoint. Webhooks are centralized — pass webhook IDs (from `create_webhook`/`list_webhooks`).

Parameters4

monitor_id	string	required	The monitor ID to update
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
webhook_ids	any	optional	Optional list of webhook IDs to assign to this monitor. Pass an empty list `[]` to clear all webhook assignments.
limit	any	optional	Optional updated maximum records per run (minimum 10).

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to update"
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "webhook_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of webhook IDs to assign to this monitor.\nPass an empty list `[]` to clear all webhook assignments."
    },
    "limit": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional updated maximum records per run (minimum 10)."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

delete_monitor

Permanently delete a monitor and stop its scheduled runs. Use when: - You want to remove a monitor entirely (use `disable_monitor` to only pause it).

Parameters2

monitor_id	string	required	The monitor ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

get_monitor_status

Get the status history of a monitor. Use when: - You want to see the timeline of a monitor's state changes (e.g. active, disabled, errored) and any related details.

Parameters2

monitor_id	string	required	The monitor ID to inspect.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "monitor_id": {
      "type": "string",
      "description": "The monitor ID to inspect."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "monitor_id"
  ],
  "additionalProperties": false
}

list_webhooks

List all your webhooks. Use when: - You want to see all webhook endpoints configured in your account. - You need to find a webhook_id to pass to monitors (via webhook_ids) or jobs.

Parameters3

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    }
  },
  "additionalProperties": false
}

create_webhook

Create a new webhook endpoint. Use when: - You want to register a URL to receive job or monitor result deliveries. - You need a webhook_id to attach to a monitor (via webhook_ids) or a job submission.

Parameters10

name	string	required	Human-readable name for the webhook (required).
url	string	required	Target URL that will receive webhook deliveries (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
type	string	optional	Optional webhook target type: 'generic' (default), 'slack', 'teams', or 'custom'. 'slack'/'teams' send pre-formatted payloads; 'generic'/'custom' send the raw result payload.
method	string	optional	HTTP method for delivery (default 'POST'). One of GET, POST, PUT, PATCH, DELETE.
delivery_mode	any	optional	Optional delivery mode: 'full' (default, whole result set in one call) or 'per_record' (one call per article).
headers	any	optional	Optional dict of custom HTTP headers to include in deliveries.
params	any	optional	Optional dict of query string parameters appended to the webhook URL.
auth	any	optional	Optional auth object forwarded with each delivery. One of: - {"type": "bearer", "token": "..."} - {"type": "api_key", "header": "X-API-Key", "value": "..."} - {"type": "basic", "username": "...", "password": "..."}
formatter_config	any	optional	Optional custom payload transformation config dict.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable name for the webhook (required)."
    },
    "url": {
      "type": "string",
      "description": "Target URL that will receive webhook deliveries (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "type": {
      "default": "",
      "type": "string",
      "description": "Optional webhook target type: 'generic' (default), 'slack', 'teams', or 'custom'.\n'slack'/'teams' send pre-formatted payloads; 'generic'/'custom' send the raw result payload."
    },
    "method": {
      "default": "POST",
      "type": "string",
      "description": "HTTP method for delivery (default 'POST'). One of GET, POST, PUT, PATCH, DELETE."
    },
    "delivery_mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional delivery mode: 'full' (default, whole result set in one call)\nor 'per_record' (one call per article)."
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional dict of custom HTTP headers to include in deliveries."
    },
    "params": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional dict of query string parameters appended to the webhook URL."
    },
    "auth": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional auth object forwarded with each delivery. One of:\n- {\"type\": \"bearer\", \"token\": \"...\"}\n- {\"type\": \"api_key\", \"header\": \"X-API-Key\", \"value\": \"...\"}\n- {\"type\": \"basic\", \"username\": \"...\", \"password\": \"...\"}"
    },
    "formatter_config": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional custom payload transformation config dict."
    }
  },
  "required": [
    "name",
    "url"
  ],
  "additionalProperties": false
}

get_webhook

Retrieve the full configuration of a specific webhook. Use when: - You want to inspect a webhook's URL, method, headers, or status by its ID.

Parameters2

webhook_id	string	required	The webhook ID to retrieve.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to retrieve."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false
}

update_webhook

Update an existing webhook's configuration. Use when: - You want to change a webhook's URL, method, headers, or other settings. - You want to enable or disable a webhook (set `is_active`). - Only the fields you provide are updated; omitted fields remain unchanged.

Parameters12

webhook_id	string	required	The webhook ID to update.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
name	any	optional	Updated webhook name.
url	any	optional	Updated target URL.
type	any	optional	Updated webhook type: 'generic', 'slack', 'teams', or 'custom'.
method	any	optional	Updated HTTP method: one of GET, POST, PUT, PATCH, DELETE.
delivery_mode	any	optional	Updated delivery mode: 'full' or 'per_record'.
headers	any	optional	Updated dict of custom HTTP headers.
params	any	optional	Updated dict of query string parameters.
auth	any	optional	Updated auth object. One of: - {"type": "bearer", "token": "..."} - {"type": "api_key", "header": "X-API-Key", "value": "..."} - {"type": "basic", "username": "...", "password": "..."}
formatter_config	any	optional	Updated formatter configuration dict.
is_active	any	optional	Set to false to disable the webhook (stop deliveries), true to re-enable it.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to update."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated webhook name."
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated target URL."
    },
    "type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated webhook type: 'generic', 'slack', 'teams', or 'custom'."
    },
    "method": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated HTTP method: one of GET, POST, PUT, PATCH, DELETE."
    },
    "delivery_mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated delivery mode: 'full' or 'per_record'."
    },
    "headers": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated dict of custom HTTP headers."
    },
    "params": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated dict of query string parameters."
    },
    "auth": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated auth object. One of:\n- {\"type\": \"bearer\", \"token\": \"...\"}\n- {\"type\": \"api_key\", \"header\": \"X-API-Key\", \"value\": \"...\"}\n- {\"type\": \"basic\", \"username\": \"...\", \"password\": \"...\"}"
    },
    "formatter_config": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Updated formatter configuration dict."
    },
    "is_active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Set to false to disable the webhook (stop deliveries), true to re-enable it."
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false
}

delete_webhook

Permanently delete a webhook endpoint. Use when: - You want to remove a webhook from your account.

Parameters2

webhook_id	string	required	The webhook ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false
}

test_webhook

Send a test delivery to a webhook endpoint. Use when: - You want to verify a webhook URL is reachable and correctly configured before attaching it to a monitor or job.

Parameters3

webhook_id	string	required	The webhook ID to test.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
payload	any	optional	Optional custom JSON object to send as the test body. If omitted, the API sends a default sample payload.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to test."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "payload": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional custom JSON object to send as the test body. If omitted,\nthe API sends a default sample payload."
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false
}

assign_webhook_resource

Map a resource (job, monitor, or monitor_group) to a webhook. Use when: - You want a webhook to fire for a specific job or monitor's deliveries.

Parameters4

webhook_id	string	required	The webhook ID to attach the resource to.
resource_type	string	required	Resource type: 'job', 'monitor', or 'monitor_group'.
resource_id	string	required	The ID of the job/monitor/monitor_group to map.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to attach the resource to."
    },
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the job/monitor/monitor_group to map."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "webhook_id",
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

list_webhook_resources

List the resources mapped to a webhook. Use when: - You want to see which jobs/monitors a webhook is attached to.

Parameters5

webhook_id	string	required	The webhook ID whose resource mappings you want.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
resource_type	string	optional	Optional filter: 'job', 'monitor', or 'monitor_group'.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID whose resource mappings you want."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "resource_type": {
      "default": "",
      "type": "string",
      "description": "Optional filter: 'job', 'monitor', or 'monitor_group'."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    }
  },
  "required": [
    "webhook_id"
  ],
  "additionalProperties": false
}

remove_webhook_resource

Unmap a resource from a webhook. Use when: - You want to stop a webhook from firing for a specific job or monitor.

Parameters4

webhook_id	string	required	The webhook ID to detach the resource from.
resource_type	string	required	Resource type: 'job', 'monitor', or 'monitor_group'.
resource_id	string	required	The ID of the mapped job/monitor/monitor_group.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to detach the resource from."
    },
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the mapped job/monitor/monitor_group."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "webhook_id",
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

list_resource_webhooks

List the webhooks mapped to a specific resource (job/monitor/monitor_group). Use when: - You have a job or monitor ID and want to know which webhooks will fire for it.

Parameters6

resource_type	string	required	Resource type: 'job', 'monitor', or 'monitor_group'.
resource_id	string	required	The ID of the job/monitor/monitor_group.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
is_active	any	optional	Optional filter — only active (true) or inactive (false) webhooks.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the job/monitor/monitor_group."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "is_active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional filter — only active (true) or inactive (false) webhooks."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    }
  },
  "required": [
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

get_webhook_history

Get the webhook delivery history for a resource (job/monitor/monitor_group). Use when: - You want to see past webhook delivery attempts and their outcomes for a specific job or monitor.

Parameters5

resource_type	string	required	Resource type: 'job', 'monitor', or 'monitor_group'.
resource_id	string	required	The ID of the job/monitor/monitor_group.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 50, max: 500).

Raw schema

{
  "type": "object",
  "properties": {
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the job/monitor/monitor_group."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 50,
      "type": "integer",
      "description": "Number of results per page (default: 50, max: 500)."
    }
  },
  "required": [
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

trigger_webhook

Manually trigger webhook delivery for a resource (job/monitor/monitor_group). Use when: - You want to (re-)send a webhook delivery on demand instead of waiting for the automatic dispatch — e.g. to replay a missed or failed delivery.

Parameters5

webhook_id	string	required	The webhook ID to deliver through.
resource_type	string	required	Resource type: 'job', 'monitor', or 'monitor_group'.
resource_id	string	required	The ID of the job/monitor/monitor_group to trigger delivery for.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
job_id	string	optional	Optional job ID whose payload should be delivered (e.g. a specific monitor run's job). If omitted, the API picks the resource's payload itself.

Raw schema

{
  "type": "object",
  "properties": {
    "webhook_id": {
      "type": "string",
      "description": "The webhook ID to deliver through."
    },
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the job/monitor/monitor_group to trigger delivery for."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "job_id": {
      "default": "",
      "type": "string",
      "description": "Optional job ID whose payload should be delivered (e.g. a specific\nmonitor run's job). If omitted, the API picks the resource's payload itself."
    }
  },
  "required": [
    "webhook_id",
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

create_dataset

Create a new dataset. Datasets are collections of entities (companies/people). Connect a dataset to a job via `submit_query(connected_dataset_ids=[...])` to narrow retrieval scope.

Parameters5

name	string	required	Human-readable dataset name (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
description	string	optional	Optional dataset description.
entity_ids	any	optional	Optional list of existing entity IDs to seed the dataset with.
project_id	string	optional	Optional project ID to associate this dataset with.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable dataset name (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "Optional dataset description."
    },
    "entity_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of existing entity IDs to seed the dataset with."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional project ID to associate this dataset with."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

list_datasets

List your datasets.

Parameters9

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).
search	string	optional	Optional text filter on the dataset name.
latest_status	string	optional	Optional status filter: 'pending', 'enriching', 'ready', or 'failed'.
sort_by	string	optional	Optional sort field: 'name', 'created_at', or 'status'.
sort_order	string	optional	Optional sort direction: 'asc' or 'desc'.
ownership	string	optional	Optional ownership filter: 'all', 'own', or 'shared'.
project_id	string	optional	Optional filter to datasets belonging to a specific project.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on the dataset name."
    },
    "latest_status": {
      "default": "",
      "type": "string",
      "description": "Optional status filter: 'pending', 'enriching', 'ready', or 'failed'."
    },
    "sort_by": {
      "default": "",
      "type": "string",
      "description": "Optional sort field: 'name', 'created_at', or 'status'."
    },
    "sort_order": {
      "default": "",
      "type": "string",
      "description": "Optional sort direction: 'asc' or 'desc'."
    },
    "ownership": {
      "default": "",
      "type": "string",
      "description": "Optional ownership filter: 'all', 'own', or 'shared'."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional filter to datasets belonging to a specific project."
    }
  },
  "additionalProperties": false
}

get_dataset

Get a single dataset's details.

Parameters2

dataset_id	string	required	The dataset ID to retrieve.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to retrieve."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id"
  ],
  "additionalProperties": false
}

update_dataset

Update a dataset's name and/or description.

Parameters4

dataset_id	string	required	The dataset ID to update.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
name	any	optional	Optional new dataset name.
description	any	optional	Optional new dataset description.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to update."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new dataset name."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new dataset description."
    }
  },
  "required": [
    "dataset_id"
  ],
  "additionalProperties": false
}

delete_dataset

Permanently delete a dataset. The entities the dataset referenced are not deleted; only the dataset and its entity associations are removed.

Parameters2

dataset_id	string	required	The dataset ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id"
  ],
  "additionalProperties": false
}

add_dataset_entities

Add existing entities to a dataset.

Parameters3

dataset_id	string	required	The dataset ID to add entities to.
entity_ids	array	required	List of entity IDs to add (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to add entities to."
    },
    "entity_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "description": "List of entity IDs to add (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id",
    "entity_ids"
  ],
  "additionalProperties": false
}

remove_dataset_entities

Remove entities from a dataset (the entities themselves are not deleted).

Parameters3

dataset_id	string	required	The dataset ID to remove entities from.
entity_ids	array	required	List of entity IDs to remove (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to remove entities from."
    },
    "entity_ids": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "description": "List of entity IDs to remove (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id",
    "entity_ids"
  ],
  "additionalProperties": false
}

list_dataset_entities

List the entities contained in a dataset.

Parameters9

dataset_id	string	required	The dataset ID whose entities you want.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100).
search	string	optional	Optional text filter on entity name.
status	string	optional	Optional status filter: 'pending', 'enriching', 'ready', or 'failed'.
entity_type	string	optional	Optional type filter: 'company' or 'person'.
sort_by	string	optional	Optional sort field: 'created_at', 'name', or 'status'.
sort_order	string	optional	Optional sort direction: 'asc' or 'desc'.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID whose entities you want."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100)."
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on entity name."
    },
    "status": {
      "default": "",
      "type": "string",
      "description": "Optional status filter: 'pending', 'enriching', 'ready', or 'failed'."
    },
    "entity_type": {
      "default": "",
      "type": "string",
      "description": "Optional type filter: 'company' or 'person'."
    },
    "sort_by": {
      "default": "",
      "type": "string",
      "description": "Optional sort field: 'created_at', 'name', or 'status'."
    },
    "sort_order": {
      "default": "",
      "type": "string",
      "description": "Optional sort direction: 'asc' or 'desc'."
    }
  },
  "required": [
    "dataset_id"
  ],
  "additionalProperties": false
}

get_dataset_status

Get the status history of a dataset (e.g. its enrichment progress over time).

Parameters2

dataset_id	string	required	The dataset ID to inspect.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to inspect."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id"
  ],
  "additionalProperties": false
}

create_dataset_from_csv

Create a new dataset by uploading a CSV file. The CSV must have at least a `name` column. For meaningful entity enrichment each row should also include a `domain` column or a `description` column (or both) — a row with only a name is accepted but produces lower-quality enrichment. Additional columns are mapped to entity attributes. Max file size is plan-dependent. To add CSV rows to an existing dataset, use `append_csv_to_dataset` instead.

Parameters5

name	string	required	Human-readable dataset name (required).
file	string	required	CSV content (required) — raw CSV text or standard base64-encoded CSV, capped at 10 MB after decoding. Server-side file paths are not accepted.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
description	string	optional	Optional dataset description.
project_id	string	optional	Optional project ID to associate this dataset with (new in 1.6.1).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable dataset name (required)."
    },
    "file": {
      "type": "string",
      "description": "CSV content (required) — raw CSV text or standard base64-encoded\nCSV, capped at 10 MB after decoding. Server-side file paths are\nnot accepted."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "Optional dataset description."
    },
    "project_id": {
      "default": "",
      "type": "string",
      "description": "Optional project ID to associate this dataset with (new in 1.6.1)."
    }
  },
  "required": [
    "name",
    "file"
  ],
  "additionalProperties": false
}

append_csv_to_dataset

Append entities from a CSV file to an existing dataset. Parses the CSV and appends its entities to the dataset. Each row must have a `name` column; include a `domain` or `description` column (or both) for meaningful enrichment. Duplicate rows (by name) are skipped. To create a new dataset from a CSV, use `create_dataset_from_csv` instead.

Parameters3

dataset_id	string	required	The dataset ID to append entities to (required).
file	string	required	CSV content (required) — raw CSV text or standard base64-encoded CSV, capped at 10 MB after decoding. Server-side file paths are not accepted.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset_id": {
      "type": "string",
      "description": "The dataset ID to append entities to (required)."
    },
    "file": {
      "type": "string",
      "description": "CSV content (required) — raw CSV text or standard base64-encoded\nCSV, capped at 10 MB after decoding. Server-side file paths are\nnot accepted."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "dataset_id",
    "file"
  ],
  "additionalProperties": false
}

create_entity

Create a single entity (a company or person). ``name`` is required plus at least one identifying field: either ``description`` or ``additional_attributes.company_attributes.domain``.

Parameters6

name	string	required	Entity name (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
entity_type	string	optional	Optional entity type: 'company' (default) or 'person'.
description	string	optional	Optional description of the entity.
external_entity_id	any	optional	Optional customer-supplied identifier linking this entity to an external system's record (new in 1.6.3).
additional_attributes	any	optional	Optional structured attributes. For companies, use `{"company_attributes": {"alternative_names": [...], "domain": "...", "key_persons": [...], "description": "..."}}`.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Entity name (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "entity_type": {
      "default": "",
      "type": "string",
      "description": "Optional entity type: 'company' (default) or 'person'."
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "Optional description of the entity."
    },
    "external_entity_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional customer-supplied identifier linking this entity to\nan external system's record (new in 1.6.3)."
    },
    "additional_attributes": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional structured attributes. For companies, use\n`{\"company_attributes\": {\"alternative_names\": [...], \"domain\": \"...\",\n\"key_persons\": [...], \"description\": \"...\"}}`."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

list_entities

List your entities.

Parameters8

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).
search	string	optional	Optional text filter on entity name.
status	string	optional	Optional status filter: 'pending', 'enriching', 'ready', or 'failed'.
entity_type	string	optional	Optional type filter: 'company' or 'person'.
sort_by	string	optional	Optional sort field: 'created_at', 'name', or 'status'.
sort_order	string	optional	Optional sort direction: 'asc' or 'desc'.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on entity name."
    },
    "status": {
      "default": "",
      "type": "string",
      "description": "Optional status filter: 'pending', 'enriching', 'ready', or 'failed'."
    },
    "entity_type": {
      "default": "",
      "type": "string",
      "description": "Optional type filter: 'company' or 'person'."
    },
    "sort_by": {
      "default": "",
      "type": "string",
      "description": "Optional sort field: 'created_at', 'name', or 'status'."
    },
    "sort_order": {
      "default": "",
      "type": "string",
      "description": "Optional sort direction: 'asc' or 'desc'."
    }
  },
  "additionalProperties": false
}

create_entities_batch

Create multiple entities in one call.

Parameters2

entities	any	required	A list of entity objects. Each object requires a ``name`` plus one identifying field for good enrichment: either a top-level ``"description"`` or ``"additional_attributes": {"company_attributes": {"domain": "..."}}``. Also accepts optional ``entity_type`` ('company'/'person'). May also be passed as a JSON-string array.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "entities": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "string"
        }
      ],
      "description": "A list of entity objects. Each object requires a ``name``\nplus one identifying field for good enrichment: either a top-level\n``\"description\"`` or ``\"additional_attributes\": {\"company_attributes\": {\"domain\": \"...\"}}``.\nAlso accepts optional ``entity_type`` ('company'/'person').\nMay also be passed as a JSON-string array."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "entities"
  ],
  "additionalProperties": false
}

get_entity

Get a single entity's details.

Parameters2

entity_id	string	required	The entity ID to retrieve.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "The entity ID to retrieve."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "entity_id"
  ],
  "additionalProperties": false
}

update_entity

Update an entity's name, description, external_entity_id, and/or attributes.

Parameters6

entity_id	string	required	The entity ID to update.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
name	any	optional	Optional new entity name.
description	any	optional	Optional new description.
external_entity_id	any	optional	Optional customer-supplied identifier linking this entity to an external system's record (new in 1.6.3).
additional_attributes	any	optional	Optional updated structured attributes (see `create_entity` for the company_attributes shape).

Raw schema

{
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "The entity ID to update."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new entity name."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new description."
    },
    "external_entity_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional customer-supplied identifier linking this entity to\nan external system's record (new in 1.6.3)."
    },
    "additional_attributes": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional updated structured attributes\n(see `create_entity` for the company_attributes shape)."
    }
  },
  "required": [
    "entity_id"
  ],
  "additionalProperties": false
}

delete_entity

Permanently delete an entity.

Parameters2

entity_id	string	required	The entity ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "The entity ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "entity_id"
  ],
  "additionalProperties": false
}

create_project

Create a new project. Projects group related resources (jobs, monitors, datasets, monitor_groups) so you can organize work and filter listings by `project_id`.

Parameters3

name	string	required	Human-readable project name (required).
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
description	string	optional	Optional project description.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Human-readable project name (required)."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "Optional project description."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

list_projects

List your projects.

Parameters5

api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).
search	string	optional	Optional text filter on the project name.
ownership	string	optional	Optional ownership filter: 'all', 'own', or 'shared'.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    },
    "search": {
      "default": "",
      "type": "string",
      "description": "Optional text filter on the project name."
    },
    "ownership": {
      "default": "",
      "type": "string",
      "description": "Optional ownership filter: 'all', 'own', or 'shared'."
    }
  },
  "additionalProperties": false
}

get_project

Get a single project's details.

Parameters2

project_id	string	required	The project ID to retrieve.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to retrieve."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false
}

update_project

Update a project's name and/or description. Only the fields you provide are changed.

Parameters4

project_id	string	required	The project ID to update.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
name	any	optional	Optional new project name.
description	any	optional	Optional new project description.

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to update."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new project name."
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional new project description."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false
}

delete_project

Delete a project. By default the project's resources (jobs, monitors, etc.) are detached but kept. Set `delete_resources=true` to also delete the contained resources.

Parameters3

project_id	string	required	The project ID to delete.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
delete_resources	boolean	optional	If true, also delete the project's resources (default false).

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to delete."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "delete_resources": {
      "default": false,
      "type": "boolean",
      "description": "If true, also delete the project's resources (default false)."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false
}

get_project_overview

Get a project's resource overview (counts grouped by resource type and status).

Parameters2

project_id	string	required	The project ID to summarize.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to summarize."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false
}

add_project_resources

Add one or more resources to a project.

Parameters3

project_id	string	required	The project ID to add resources to.
resources	any	required	A list of resource objects, each `{"resource_type": ..., "resource_id": ...}`. `resource_type` is one of: 'job', 'monitor', 'dataset', 'monitor_group'. May also be passed as a JSON-string array for client compatibility.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to add resources to."
    },
    "resources": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "string"
        }
      ],
      "description": "A list of resource objects, each `{\"resource_type\": ..., \"resource_id\": ...}`.\n`resource_type` is one of: 'job', 'monitor', 'dataset', 'monitor_group'.\nMay also be passed as a JSON-string array for client compatibility."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "project_id",
    "resources"
  ],
  "additionalProperties": false
}

list_project_resources

List the resources contained in a project.

Parameters5

project_id	string	required	The project ID whose resources you want.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.
resource_type	string	optional	Optional filter: 'job', 'monitor', 'dataset', or 'monitor_group'.
page	integer	optional	Page number for pagination (default: 1).
page_size	integer	optional	Number of results per page (default: 100, max: 1000).

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID whose resources you want."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    },
    "resource_type": {
      "default": "",
      "type": "string",
      "description": "Optional filter: 'job', 'monitor', 'dataset', or 'monitor_group'."
    },
    "page": {
      "default": 1,
      "type": "integer",
      "description": "Page number for pagination (default: 1)."
    },
    "page_size": {
      "default": 100,
      "type": "integer",
      "description": "Number of results per page (default: 100, max: 1000)."
    }
  },
  "required": [
    "project_id"
  ],
  "additionalProperties": false
}

remove_project_resource

Remove a single resource from a project.

Parameters4

project_id	string	required	The project ID to remove the resource from.
resource_type	string	required	Resource type: 'job', 'monitor', 'dataset', or 'monitor_group'.
resource_id	string	required	The ID of the resource to remove.
api_key	string	optional	CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "The project ID to remove the resource from."
    },
    "resource_type": {
      "type": "string",
      "description": "Resource type: 'job', 'monitor', 'dataset', or 'monitor_group'."
    },
    "resource_id": {
      "type": "string",
      "description": "The ID of the resource to remove."
    },
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "required": [
    "project_id",
    "resource_type",
    "resource_id"
  ],
  "additionalProperties": false
}

get_user_limits

Retrieve plan features and current usage limits for your API key. Use when: - You want to know how many records/jobs/monitors your plan allows. - You want to check current usage against plan limits before running a large job.

Parameters1

api_key

string

optional

CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var."
    }
  },
  "additionalProperties": false
}

check_health

Check API health status. This tool maps to GET /health and does not require an API key.

Parameters1

api_key

string

optional

Optional CatchAll API key.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "Optional CatchAll API key."
    }
  },
  "additionalProperties": false
}

get_version

Get current API version. This tool maps to GET /version and does not require an API key.

Parameters1

api_key

string

optional

Optional CatchAll API key.

Raw schema

{
  "type": "object",
  "properties": {
    "api_key": {
      "default": "",
      "type": "string",
      "description": "Optional CatchAll API key."
    }
  },
  "additionalProperties": false
}

README.md10 KBView on GitHub

Newscatcher CatchAll MCP Server

MCP server for the NewsCatcher CatchAll Web Search API.

Quick Start — Use Our Hosted Server

You don't need to clone or run this repo to use the MCP — NewsCatcher runs a hosted instance:

code

https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY

Get a CatchAll API key at platform.newscatcherapi.com, then connect:

json

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"
    }
  }
}

Or via Claude Code CLI:

bash

claude mcp add --transport http catchall "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"

Full integration docs: https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp

Prefer to run the server yourself (locally or self-hosted)? See Running below.

Tool To Endpoint Mapping

Jobs

MCP Tool	Method	Endpoint
`initialize_query`	`POST`	`/catchAll/initialize`
`submit_query`	`POST`	`/catchAll/submit`
`validate_query`	`POST`	`/catchAll/validate`
`continue_job`	`POST`	`/catchAll/continue`
`list_user_jobs`	`GET`	`/catchAll/jobs/user`
`get_job_status`	`GET`	`/catchAll/status/{job_id}`
`pull_results`	`GET`	`/catchAll/pull/{job_id}`
`pull_job_csv`	`GET`	`/catchAll/pull/{job_id}/csv`
`delete_job`	`DELETE`	`/catchAll/jobs/{job_id}`

Monitors

MCP Tool	Method	Endpoint
`create_monitor`	`POST`	`/catchAll/monitors/create`
`update_monitor`	`PATCH`	`/catchAll/monitors/{monitor_id}`
`delete_monitor`	`DELETE`	`/catchAll/monitors/{monitor_id}`
`list_monitors`	`GET`	`/catchAll/monitors/`
`list_monitor_jobs`	`GET`	`/catchAll/monitors/{monitor_id}/jobs`
`get_monitor_status`	`GET`	`/catchAll/monitors/{monitor_id}/status`
`pull_monitor_results`	`GET`	`/catchAll/monitors/pull/{monitor_id}`
`pull_monitor_csv`	`GET`	`/catchAll/monitors/pull/{monitor_id}/csv`
`enable_monitor`	`POST`	`/catchAll/monitors/{monitor_id}/enable`
`disable_monitor`	`POST`	`/catchAll/monitors/{monitor_id}/disable`

Webhooks

MCP Tool	Method	Endpoint
`list_webhooks`	`GET`	`/catchAll/webhooks`
`create_webhook`	`POST`	`/catchAll/webhooks`
`get_webhook`	`GET`	`/catchAll/webhooks/{webhook_id}`
`update_webhook`	`PATCH`	`/catchAll/webhooks/{webhook_id}`
`delete_webhook`	`DELETE`	`/catchAll/webhooks/{webhook_id}`
`test_webhook`	`POST`	`/catchAll/webhooks/{webhook_id}/test`
`assign_webhook_resource`	`POST`	`/catchAll/webhooks/{webhook_id}/resources`
`list_webhook_resources`	`GET`	`/catchAll/webhooks/{webhook_id}/resources`
`remove_webhook_resource`	`DELETE`	`/catchAll/webhooks/{webhook_id}/resources/{resource_type}/{resource_id}`
`list_resource_webhooks`	`GET`	`/catchAll/resources/{resource_type}/{resource_id}/webhooks`
`get_webhook_history`	`GET`	`/catchAll/webhook-history`
`trigger_webhook`	`POST`	`/catchAll/webhook/trigger/{resource_type}/{resource_id}`

Projects

MCP Tool	Method	Endpoint
`create_project`	`POST`	`/catchAll/projects/`
`list_projects`	`GET`	`/catchAll/projects/`
`get_project`	`GET`	`/catchAll/projects/{project_id}`
`update_project`	`PATCH`	`/catchAll/projects/{project_id}`
`delete_project`	`DELETE`	`/catchAll/projects/{project_id}`
`get_project_overview`	`GET`	`/catchAll/projects/{project_id}/overview`
`add_project_resources`	`POST`	`/catchAll/projects/{project_id}/resources`
`list_project_resources`	`GET`	`/catchAll/projects/{project_id}/resources`
`remove_project_resource`	`DELETE`	`/catchAll/projects/{project_id}/resources/{resource_type}/{resource_id}`

Datasets

MCP Tool	Method	Endpoint
`create_dataset`	`POST`	`/catchAll/datasets/`
`list_datasets`	`GET`	`/catchAll/datasets/`
`get_dataset`	`GET`	`/catchAll/datasets/{dataset_id}`
`update_dataset`	`PATCH`	`/catchAll/datasets/{dataset_id}`
`delete_dataset`	`DELETE`	`/catchAll/datasets/{dataset_id}`
`add_dataset_entities`	`POST`	`/catchAll/datasets/{dataset_id}/entities`
`remove_dataset_entities`	`DELETE`	`/catchAll/datasets/{dataset_id}/entities`
`list_dataset_entities`	`POST`	`/catchAll/datasets/{dataset_id}/entities/list`
`get_dataset_status`	`GET`	`/catchAll/datasets/{dataset_id}/status`
`create_dataset_from_csv`	`POST`	`/catchAll/datasets/upload`
`append_csv_to_dataset`	`POST`	`/catchAll/datasets/{dataset_id}/upload`

CSV uploads (v1.6.1): create_dataset_from_csv and append_csv_to_dataset take the CSV content in the file parameter — raw CSV text or standard base64. They never read a path from the server's filesystem, so they stay safe on a remote/hosted MCP. Inline CSV content is capped at a hard 10 MB (after base64 decoding). create_dataset_from_csv also accepts the new optional project_id field.

Entities

MCP Tool	Method	Endpoint
`create_entity`	`POST`	`/catchAll/entities/`
`list_entities`	`GET`	`/catchAll/entities/`
`create_entities_batch`	`POST`	`/catchAll/entities/batch`
`get_entity`	`GET`	`/catchAll/entities/{entity_id}`
`update_entity`	`PATCH`	`/catchAll/entities/{entity_id}`
`delete_entity`	`DELETE`	`/catchAll/entities/{entity_id}`

external_entity_id (v1.6.3): create_entity and update_entity accept an optional external_entity_id string — a customer-supplied identifier that links the entity to a record in an external system.

User & Meta

MCP Tool	Method	Endpoint
`get_user_limits`	`POST`	`/catchAll/user/limits`
`check_health`	`GET`	`/health`
`get_version`	`GET`	`/version`

Authentication

API key precedence (highest to lowest):

api_key tool parameter
x-api-key request header
Authorization: Bearer <key> request header
URL query parameter ?apiKey=...
CATCHALL_API_KEY environment variable

check_health and get_version do not require API key auth.

Hosted deployment (FastMCP Gateway)

When deployed via fastmcp.app, a stateless gateway sits in front of the server. The gateway forwards HTTP headers to the backend but not URL query parameters. Use the x-api-key header or CATCHALL_API_KEY environment variable instead of ?apiKey=.

Claude Code / Cursor:

json

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://YOUR-DEPLOYMENT.fastmcp.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Or via CLI:

bash

claude mcp add --transport http catchall "https://YOUR-DEPLOYMENT.fastmcp.app/mcp" \
  --header "x-api-key: YOUR_API_KEY"

Direct server access (no gateway): ?apiKey=YOUR_KEY in the URL still works.

Core Workflow (Jobs)

Optional: call initialize_query to preview validators/enrichments/date window.
initialize_query is preview-only (it does not create a job) and suggestions are non-deterministic.
Submit with submit_query (query required). You can send only query; omitted optional fields are auto-selected/generated.
Optional fields are independent: provide any subset (for example, custom validators only), omitted ones are still auto-generated.
start_date/end_date filter web page discovery dates, not event dates in extracted content.
For event-time accuracy, use event-focused validators/enrichments and verify event_date in pulled results.
Poll get_job_status: first check after ~1-2 minutes, then every 30-60 seconds, stop on completed or failed.
Pull with pull_results; partial data appears during enriching.
Paginate while page < total_pages to retrieve all available records.
Use continue_job only to process more records (cost-affecting). It applies only to jobs originally submitted with limit.
continue_job.new_limit is optional; if omitted, API defaults to your plan maximum.
page/page_size/total_pages represent already-available records; use progress_validated < candidate_records to detect if more records may still appear.

Limit vs Page Size

limit (submit_query, continue_job) controls how many records are processed and therefore affects cost. If provided, must be >= 10. Omit to retrieve everything up to your plan's maximum.
page_size (pull_results, list_user_jobs) controls pagination only and does not affect processing cost.
pull_results.page_size default is 100.
page_size range is 1..1000.
pull_results response includes error (failed jobs) and limit (applied job limit).

API-Enforced Monitor Constraints

create_monitor.backfill=true: reference job end_date must be within the last 7 days.
create_monitor.backfill=false: reference job age constraint does not apply.
Monitor minimum schedule frequency depends on plan.
create_monitor supports optional limit (minimum 10), backfill (default true), timezone, webhook_ids, and project_id.
Webhooks are centralized in v1.5.3: register them with create_webhook, then attach by ID via create_monitor.webhook_ids / update_monitor.webhook_ids (no inline webhook config).
Monitors are only supported for base jobs (not lite).
enable_monitor supports optional backfill.
update_monitor updates webhook_ids and/or run limit (pass webhook_ids=[] to clear assignments).
list_monitors supports pagination via page and page_size plus search, ownership, and project_id filters; it returns total, page, page_size, total_pages, monitors.

Enrichment Output Notes

enrichment.enrichment_confidence is always present.
Company enrichments are structured objects with:
- source_text
- confidence
- metadata.name
- metadata.domain_url
- metadata.domain_url_confidence

Error Handling

Tools return:

Pretty JSON string on success.
"Error: ..." for validation/API errors.
"Unexpected error: ..." for unhandled exceptions.

Running

Install dependencies:

bash

pip install -r requirements.txt

Run over stdio:

bash

python server.py

Run over HTTP (if fastmcp CLI is available):

bash

fastmcp run server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000

Install

Tools (60)

submit_queryinitialize_queryget_job_statuspull_resultspull_job_csvcontinue_joblist_user_jobsdelete_job

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://catchall-mcp.newscatcherapi.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "catchall": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://catchall-mcp.newscatcherapi.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.