# API

Authenticate, page through mentions, handle errors, and every REST endpoint on one page.

Base URL: `https://prospy.io/api/v1`. The full schema is the [OpenAPI 3.1 spec](/api/v1/openapi.json).

## Authenticate
Create a key in [Integrations → API & MCP](/integrations/api) and keep it server-side. Keys start with `psy_live_` and are shown once. Read keys allow GET requests; full keys also allow writes within your project role. An active subscription is required.

```bash
curl https://prospy.io/api/v1/projects \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

## Paginate
List mentions returns `data` and `nextCursor`. `limit` is 1–100 (default 25). Pass `nextCursor` back as `cursor` with the same filters and sort, and stop when it is null. Arrays accept repeated or comma-separated values: `platforms=Twitter,Reddit`. Dates are ISO 8601; `from` is inclusive and `to` exclusive.

## Handle errors
Errors look like `{"error":{"code":"validation_error","message":"Invalid request"}}`.

| Status | What to do |
| --- | --- |
| 400 | Fix parameter types, required fields or JSON. |
| 401 | Check the key and whether it was revoked. |
| 403 | Check subscription, key scope and project role. |
| 404 | Check the path and resource ID. |
| 409 | Resolve the conflict or idempotency-key mismatch. |
| 429 | Wait for `Retry-After`. Limits are per user across all keys and MCP. |
| 500 | Retry with backoff. |

Send an `Idempotency-Key` on POST to retry safely. Responses replay for 24 hours; reusing a key for a different request returns 409.

## Projects endpoints

### GET /me

Get the API key's user identifier and actor context. MCP tool: `get_me`.

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/me' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"get_me","arguments":{}}`

### GET /projects

List projects the actor can access, including their role. MCP tool: `list_projects`.

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_projects","arguments":{}}`

### POST /projects

Create a project owned by the actor, with optional starting brand and competitor keywords, within plan limits, and start its first scan. MCP tool: `create_project`.

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `url` | No | string | Format: uri. |
| `timezone` | No | string | Minimum length: 1. Maximum length: 100. |
| `brandKeywords` | No | string[] | Brand and product keywords, added to the Brand group. Maximum items: 100. |
| `competitorKeywords` | No | string[] | Competitor names, added to the Competitors group. Maximum items: 100. |
| `platforms` | No | ("Twitter" \| "Reddit" \| "HackerNews" \| "Bluesky" \| "YouTube" \| "LinkedIn" \| "Threads" \| "TikTok" \| "Quora" \| "ProductHunt" \| "GitHub" \| "Medium")[] | Platforms the starting keywords watch. Omit to watch every platform. Maximum items: 12. |
| `categories` | No | object[] | Replaces the default mention categories. Maximum items: 50. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"create_project","arguments":{"input":{"name":"Example"}}}`

### GET /projects/{projectId}

Get a project. Requires viewer access. MCP tool: `get_project`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"get_project","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### PATCH /projects/{projectId}

Update project settings; public settings require owner access. MCP tool: `update_project`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | No | string | Minimum length: 1. Maximum length: 200. |
| `url` | No | string | Format: uri. |
| `timezone` | No | string | Minimum length: 1. Maximum length: 100. |
| `digestEnabled` | No | boolean |  |
| `digestHour` | No | integer | Minimum: 0. Maximum: 23. |
| `isPublic` | No | boolean |  |
| `publicSlug` | No | string \| null |  |
| `publicDescription` | No | string \| null |  |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"update_project","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### GET /projects/{projectId}/usage

Get current monthly usage against the project owner's plan. MCP tool: `get_usage`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/usage' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"get_usage","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### GET /projects/{projectId}/analytics

Aggregate mentions over an ISO date range; defaults to the last 30 days. MCP tool: `get_analytics`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |
| `from` | query | No | string | Format: date-time. |
| `to` | query | No | string | Format: date-time. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/analytics' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"get_analytics","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

## Mentions endpoints

### GET /projects/{projectId}/mentions

Search mentions by dates, platforms, statuses, sentiments, intents, categories, keywords, groups, author, lead score, text and Google ranking (ranksOnGoogle, sort google_rank), with cursor pagination. MCP tool: `list_mentions`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |
| `from` | query | No | string | Format: date-time. |
| `to` | query | No | string | Format: date-time. |
| `platforms` | query | No | ("Twitter" \| "Reddit" \| "HackerNews" \| "Bluesky" \| "YouTube" \| "LinkedIn" \| "Threads" \| "TikTok" \| "Quora" \| "ProductHunt" \| "GitHub" \| "Medium")[] | Maximum items: 12. |
| `statuses` | query | No | ("open" \| "done" \| "follow_up")[] | Maximum items: 3. |
| `sentiments` | query | No | ("positive" \| "neutral" \| "negative")[] | Maximum items: 3. |
| `intents` | query | No | ("buyer" \| "switching" \| "question" \| "complaint" \| "praise" \| "none")[] | Maximum items: 6. |
| `categoryIds` | query | No | string[] | Maximum items: 100. |
| `keywordIds` | query | No | string[] | Maximum items: 100. |
| `keywordGroupIds` | query | No | string[] | Maximum items: 100. |
| `author` | query | No | string | Minimum length: 1. Maximum length: 100. |
| `minLeadScore` | query | No | integer | Minimum: 0. Maximum: 100. |
| `search` | query | No | string | Minimum length: 1. Maximum length: 200. |
| `ranksOnGoogle` | query | No | boolean |  |
| `sort` | query | No | "newest" \| "oldest" \| "lead_score" \| "engagement" \| "google_rank" |  |
| `limit` | query | No | integer | Minimum: 1. Maximum: 100. Default: 25. |
| `cursor` | query | No | string | Maximum length: 500. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/mentions' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_mentions","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### GET /mentions/{id}

Get one mention. Requires viewer access. MCP tool: `get_mention`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/mentions/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"get_mention","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### PATCH /mentions/{id}

Update a mention's status or category. Requires editor access. MCP tool: `update_mention_status`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `status` | No | "open" \| "done" \| "follow_up" |  |
| `feedback` | No | "good" \| "bad" \| null |  |
| `categoryId` | No | string \| null |  |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/mentions/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"open"}'
```

MCP: `{"name":"update_mention_status","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"status":"open"}}}`

### POST /mentions/{id}/irrelevant

Delete and block re-ingestion of an irrelevant mention, optionally blocking its author. Requires editor access. MCP tool: `mark_mention_irrelevant`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `blockAuthor` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/mentions/00000000-0000-4000-8000-000000000001/irrelevant' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"blockAuthor":true}'
```

MCP: `{"name":"mark_mention_irrelevant","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"blockAuthor":true}}}`

### POST /mentions/{id}/translate

Translate a mention to English and return it. Requires editor access. MCP tool: `translate_mention`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/mentions/00000000-0000-4000-8000-000000000001/translate' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"translate_mention","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

## Keywords endpoints

### GET /projects/{projectId}/keyword-groups

List a project's keyword groups. MCP tool: `list_keyword_groups`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/keyword-groups' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_keyword_groups","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/keyword-groups

Create a keyword group. Requires editor access. MCP tool: `create_keyword_group`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `kind` | No | "brand" \| "competitors" \| "custom" |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/keyword-groups' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"create_keyword_group","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### PATCH /keyword-groups/{id}

Rename or reorder a keyword group. MCP tool: `update_keyword_group`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | No | string | Minimum length: 1. Maximum length: 200. |
| `position` | No | integer | Minimum: 0. Maximum: 10000. |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/keyword-groups/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"update_keyword_group","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### DELETE /keyword-groups/{id}

Delete a custom keyword group; built-in groups are protected. MCP tool: `delete_keyword_group`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/keyword-groups/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_keyword_group","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### GET /projects/{projectId}/keywords

List a project's keywords and matching settings. MCP tool: `list_keywords`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/keywords' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_keywords","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/keywords

Create a keyword within plan limits. Requires editor access. MCP tool: `create_keyword`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `keyword` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `groupId` | No | string \| null |  |
| `platforms` | No | ("Twitter" \| "Reddit" \| "HackerNews" \| "Bluesky" \| "YouTube" \| "LinkedIn" \| "Threads" \| "TikTok" \| "Quora" \| "ProductHunt" \| "GitHub" \| "Medium")[] \| null |  |
| `aliases` | No | string[] | Maximum items: 100. |
| `excludeTerms` | No | string[] | Maximum items: 100. |
| `exactMatch` | No | boolean |  |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/keywords' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"social listening"}'
```

MCP: `{"name":"create_keyword","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"keyword":"social listening"}}}`

### PATCH /keywords/{id}

Update keyword matching settings. Requires editor access. MCP tool: `update_keyword`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `keyword` | No | string | Minimum length: 1. Maximum length: 200. |
| `groupId` | No | string \| null |  |
| `platforms` | No | ("Twitter" \| "Reddit" \| "HackerNews" \| "Bluesky" \| "YouTube" \| "LinkedIn" \| "Threads" \| "TikTok" \| "Quora" \| "ProductHunt" \| "GitHub" \| "Medium")[] \| null |  |
| `aliases` | No | string[] | Maximum items: 100. |
| `excludeTerms` | No | string[] | Maximum items: 100. |
| `exactMatch` | No | boolean |  |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/keywords/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"social listening"}'
```

MCP: `{"name":"update_keyword","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"keyword":"social listening"}}}`

### DELETE /keywords/{id}

Delete a keyword. Requires editor access. MCP tool: `delete_keyword`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/keywords/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_keyword","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

## Categories and views endpoints

### GET /projects/{projectId}/categories

List a project's categories. MCP tool: `list_categories`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/categories' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_categories","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/categories

Create a mention category. Requires editor access. MCP tool: `create_category`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `description` | No | string | Maximum length: 2000. |
| `color` | No | string | Minimum length: 1. Maximum length: 40. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/categories' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"create_category","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### PATCH /categories/{id}

Update a category's name, description, color or position. MCP tool: `update_category`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | No | string | Minimum length: 1. Maximum length: 200. |
| `description` | No | string | Maximum length: 2000. |
| `color` | No | string | Minimum length: 1. Maximum length: 40. |
| `position` | No | integer | Minimum: 0. Maximum: 10000. |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/categories/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"update_category","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### DELETE /categories/{id}

Delete a category, preserving its mentions without that category. MCP tool: `delete_category`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/categories/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_category","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### GET /projects/{projectId}/saved-views

List saved mention filters. MCP tool: `list_saved_views`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/saved-views' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_saved_views","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/saved-views

Save a named set of mention filters. MCP tool: `create_saved_view`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `filters` | Yes | object |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/saved-views' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example","filters":{"from":"2026-10-01T00:00:00Z"}}'
```

MCP: `{"name":"create_saved_view","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"name":"Example","filters":{"from":"2026-10-01T00:00:00Z"}}}}`

### PATCH /saved-views/{id}

Update a saved view's name, filters or position. MCP tool: `update_saved_view`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | No | string | Minimum length: 1. Maximum length: 200. |
| `filters` | No | object |  |
| `position` | No | integer | Minimum: 0. Maximum: 10000. |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/saved-views/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"update_saved_view","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### DELETE /saved-views/{id}

Delete a saved view. MCP tool: `delete_saved_view`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/saved-views/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_saved_view","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

## Alerts endpoints

### GET /projects/{projectId}/alerts

List project alert rules. MCP tool: `list_alerts`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/alerts' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_alerts","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/alerts

Create an email, Slack or Discord alert within plan limits. MCP tool: `create_alert`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | Yes | string | Minimum length: 1. Maximum length: 200. |
| `targetType` | Yes | "all" \| "group" \| "keyword" \| "author" |  |
| `targetId` | No | string \| null |  |
| `targetValue` | No | string \| null |  |
| `minLeadScore` | No | integer | Minimum: 0. Maximum: 100. |
| `categoryIds` | No | string[] | Maximum items: 100. |
| `sentiments` | No | ("positive" \| "neutral" \| "negative")[] | Maximum items: 3. |
| `channel` | Yes | "email" \| "slack" \| "discord" \| "webhook" |  |
| `destination` | Yes | string | Minimum length: 1. Maximum length: 2000. |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/alerts' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example","targetType":"all","channel":"email","destination":"alerts@example.com"}'
```

MCP: `{"name":"create_alert","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"name":"Example","targetType":"all","channel":"email","destination":"alerts@example.com"}}}`

### PATCH /alerts/{id}

Update an alert rule. Requires editor access. MCP tool: `update_alert`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `name` | No | string | Minimum length: 1. Maximum length: 200. |
| `targetType` | No | "all" \| "group" \| "keyword" \| "author" |  |
| `targetId` | No | string \| null |  |
| `targetValue` | No | string \| null |  |
| `minLeadScore` | No | integer | Minimum: 0. Maximum: 100. |
| `categoryIds` | No | string[] | Maximum items: 100. |
| `sentiments` | No | ("positive" \| "neutral" \| "negative")[] | Maximum items: 3. |
| `channel` | No | "email" \| "slack" \| "discord" \| "webhook" |  |
| `destination` | No | string | Minimum length: 1. Maximum length: 2000. |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/alerts/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Example"}'
```

MCP: `{"name":"update_alert","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"name":"Example"}}}`

### DELETE /alerts/{id}

Delete an alert rule. MCP tool: `delete_alert`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/alerts/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_alert","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### POST /alerts/{id}/test

Send a test notification to an alert destination. MCP tool: `test_alert`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/alerts/00000000-0000-4000-8000-000000000001/test' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"test_alert","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

## Webhooks endpoints

### GET /projects/{projectId}/webhooks

List webhook endpoints without signing secrets. MCP tool: `list_webhooks`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/webhooks' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_webhooks","arguments":{"projectId":"00000000-0000-4000-8000-000000000001"}}`

### POST /projects/{projectId}/webhooks

Create a webhook endpoint; returns the signing secret once. MCP tool: `create_webhook`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `projectId` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `url` | Yes | string | Format: uri. |
| `description` | No | string | Maximum length: 2000. |
| `eventTypes` | No | ("mention.created" \| "mention.updated" \| "mention.status_changed" \| "mention.marked_irrelevant" \| "keyword.created" \| "keyword.updated" \| "keyword.deleted" \| "alert.triggered" \| "scan.completed")[] | Maximum items: 9. |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/projects/00000000-0000-4000-8000-000000000001/webhooks' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/webhooks/prospy"}'
```

MCP: `{"name":"create_webhook","arguments":{"projectId":"00000000-0000-4000-8000-000000000001","input":{"url":"https://example.com/webhooks/prospy"}}}`

### PATCH /webhooks/{id}

Update an endpoint URL, events or enabled state. MCP tool: `update_webhook`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

JSON body:

| Field | Required | Type | Notes |
| --- | --- | --- | --- |
| `url` | No | string | Format: uri. |
| `description` | No | string | Maximum length: 2000. |
| `eventTypes` | No | ("mention.created" \| "mention.updated" \| "mention.status_changed" \| "mention.marked_irrelevant" \| "keyword.created" \| "keyword.updated" \| "keyword.deleted" \| "alert.triggered" \| "scan.completed")[] | Maximum items: 9. |
| `enabled` | No | boolean |  |

Scope: full. Needs editor role or higher.

```bash
curl -X PATCH 'https://prospy.io/api/v1/webhooks/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/webhooks/prospy"}'
```

MCP: `{"name":"update_webhook","arguments":{"id":"00000000-0000-4000-8000-000000000001","input":{"url":"https://example.com/webhooks/prospy"}}}`

### DELETE /webhooks/{id}

Delete a webhook endpoint. MCP tool: `delete_webhook`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X DELETE 'https://prospy.io/api/v1/webhooks/00000000-0000-4000-8000-000000000001' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"delete_webhook","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### POST /webhooks/{id}/rotate-secret

Replace an endpoint's signing secret and return the new secret once. MCP tool: `rotate_webhook_secret`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/webhooks/00000000-0000-4000-8000-000000000001/rotate-secret' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"rotate_webhook_secret","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### GET /webhooks/{id}/deliveries

List webhook delivery attempts with cursor pagination. MCP tool: `list_webhook_deliveries`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |
| `limit` | query | No | integer | Minimum: 1. Maximum: 100. Default: 25. |
| `cursor` | query | No | string | Maximum length: 500. |

Scope: read or full.

```bash
curl -X GET 'https://prospy.io/api/v1/webhooks/00000000-0000-4000-8000-000000000001/deliveries' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"list_webhook_deliveries","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### POST /webhook-deliveries/{id}/replay

Replay a webhook delivery with its original event id. MCP tool: `replay_webhook_delivery`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/webhook-deliveries/00000000-0000-4000-8000-000000000001/replay' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"replay_webhook_delivery","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`

### POST /webhooks/{id}/test

Send a sample mention.created event to an endpoint. MCP tool: `test_webhook`.

| Parameter | In | Required | Type | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | Yes | string | Format: uuid. |

Scope: full. Needs editor role or higher.

```bash
curl -X POST 'https://prospy.io/api/v1/webhooks/00000000-0000-4000-8000-000000000001/test' \
  -H "Authorization: Bearer $PROSPY_API_KEY"
```

MCP: `{"name":"test_webhook","arguments":{"id":"00000000-0000-4000-8000-000000000001"}}`