Saved searches and filters
| Tool | What it does |
|---|---|
recent_searches | List the caller’s recent meaningful searches by entity type with pagination. |
saved_search_delete | Permanently delete one caller-owned saved-search definition after approval. |
saved_search_list | List the caller’s saved searches, criteria and IDs with name search and pagination. |
tag_list | List exactly one deal, sequence, or recording tag vocabulary selected by scope. |
recent_searches
List the caller’s recent meaningful searches by entity type with pagination.
List the user’s past searches — type, the filters used, the original natural-language prompt if any, and when it ran — most recent first, paginated. Use to let the user resume, reference, or re-run a prior search.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/recent-searches |
| MCP tool | recent_searches on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-based: page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
search_type | string (enum) | No | One of: PEOPLE, COMPANIES. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
saved_search_delete
Permanently delete one caller-owned saved-search definition after approval.
Delete a saved search the user names explicitly. Never suggest deletion proactively.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/saved-search-delete |
| MCP tool | saved_search_delete on https://mcp.prospeo.io |
| Effect | Deletes or removes data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Recommended: MCP clients should confirm with the user before calling. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
saved_search_oid | string | Yes | MongoDB ObjectId Pattern ^[0-9a-fA-F]{24}$. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
saved_search_list
List the caller’s saved searches, criteria and IDs with name search and pagination.
List the user’s saved searches (name, type, filter criteria, timestamps), with optional name search and pagination. Use to answer ‘what saved searches do I have?’ or to find a saved_search_id to pass into a subsequent search.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/saved-search-list |
| MCP tool | saved_search_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Page-based: page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | From 1 to any. Default 1. |
search | string | No | Default "". |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.
tag_list
List exactly one deal, sequence, or recording tag vocabulary selected by scope.
List exactly one of the team’s tag vocabularies, selected by REQUIRED scope: deal, sequence, or recording. Resolve user-supplied tag names to the IDs expected by the matching deal_search, sequence_search, or recording_search filter. Never merge vocabularies, reuse an ID across scopes, choose a default scope, or fall back to another scope after a permission denial. Sequence scope requires sequences.team.read; deal and recording require the authenticated caller but no additional RBAC key. Deal color is deliberately omitted; no derived color or owner extraction is required.
| Endpoint | POST https://api.prospeo.io/api/v2/tools/tag-list |
| MCP tool | tag_list on https://mcp.prospeo.io |
| Effect | Reads data. |
| Credits | Free, uses no credits. |
| Permission | No role permission beyond API access. |
| Confirmation | Not needed. |
| Pagination | Returns one page. |
Request
Send POST with your API key in the X-KEY header and a JSON body. Unknown fields and query parameters are rejected. The full JSON Schema is served with the tool list.
| Parameter | Type | Required | Description |
|---|---|---|---|
scope | string (enum) | Yes | One of: deal, sequence, recording. |
Response
{"ok": true, "summary": "...", "payload": {...}} on success. Errors return {"ok": false, "code", "message", "retryable"}; see error codes.