---
title: Build on Venom People
description: Search, add and update the people a member knows, log interactions and draft follow-ups from code or an agent, over REST or MCP. People is personal, so every call acts for one member.
section: developers
order: 30
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/people/tools.ts, services/nodejs-cloud/lib/people/auth.ts, services/nodejs-cloud/lib/people/mcp.ts, services/nodejs-cloud/lib/people/index.ts, services/nodejs-cloud/lib/mcp/workspace.ts, services/nodejs-cloud/lib/mcp/rest.ts, services/nodejs-cloud/components/console/rbac.ts]
features: []
---

Venom People is each member's own memory of the people they know: profiles, handles, interactions, context cards,
circles and follow-ups. A member can share a person with a team or the whole organisation. Every action is an MCP tool
and a REST route under `/api/v1/people`, and every call acts for one member and sees what that member sees.

## What you can build {#build}

- **Log touches from your other tools.** After a call, a meeting or an email, find the person
  (`GET /api/v1/people?query=…`) and log what happened (`POST /api/v1/people/{person}/interactions`). Promises and
  next steps in the summary become open loops on the person's context card.
- **Add people from a sign-up or a card scan.** Add a person with their handles and a first interaction
  (`POST /api/v1/people`), or send text, a vCard or images to capture (`POST /api/v1/people/capture`) and confirm the
  drafts.
- **A daily follow-up digest.** Read today's follow-ups (`GET /api/v1/people/followups`), draft a message for one
  (`POST /api/v1/people/followups/draft`) and record it sent once the member sends it
  (`POST /api/v1/people/followups/{followup}/send`). Venom never sends the message.
- **Warm intros.** Search who in the organisation knows someone at a company (`GET /api/v1/people/network`) and ask
  that colleague for an intro (`POST /api/v1/people/intros`).
- **Imports.** Send a CSV, vCard, WhatsApp chat or Telegram export (`POST /api/v1/people/import`); it is read only
  until `confirm`.

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/people`, server name `venom-people` |
| Connect | `claude mcp add --transport http venom-people https://cloud.usevenom.dev/workspace/mcp/people` |
| MCP tools | 135 (50 read, 85 write) |
| OAuth scopes | `people:read` `people:write` |
| REST twin | 136 routes under `https://cloud.usevenom.dev/api/v1` |
| Webhook events | `people.person.created`, `people.person.updated`, `people.person.removed` |

## Authentication and scopes {#scopes}

People holds personal data, so the caller must be a member:

- A **personal API key** acts for its member.
- An **OAuth app** acts for the member who connected it. It needs `people:read` to use People at all and
  `people:write` to change anything.
- A **team key** has no member and is refused every People tool, in words, with `403` over REST. So is a service agent
  an admin scoped to other apps. Use a member's personal key instead.

The member's role decides the rest. Every member, whatever their role, writes their own private people. Sharing a
person, and changing people others shared, needs a role that writes in People: owner, admin or developer. Billing and
viewer members read what was shared with them and keep their own private people.

The caller sees exactly what the member sees: their own people in full, and people others shared with them without
notes, handles, cards or interactions. A person the member cannot see answers as if it did not exist.

People is not an add-on: every organisation has it. Tools that call a model (context cards, drafts, recall, image
reading) go through the organisation's gear, under its daily People AI cap.

## Worked example {#example}

Find the person, then log a call with them:

```bash
curl "$VENOM_CLOUD/api/v1/people?query=Sarah%20Chen%20FrostCo&limit=5" \
  -H "Authorization: Bearer $VENOM_API_KEY"

curl -X POST "$VENOM_CLOUD/api/v1/people/<person-id>/interactions" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"kind": "call", "summary": "Walked through GPU pricing for the warehouse cluster. I promised a revised quote by Friday.", "occurred_at": "2026-11-09", "channel": "phone", "direction": "out"}'
```

The same call logged over MCP, from any client connected to `/workspace/mcp/people`:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "people_interaction_create",
              "arguments": { "person": "<person-id>", "kind": "call",
                             "summary": "Walked through GPU pricing for the warehouse cluster. I promised a revised quote by Friday.",
                             "occurred_at": "2026-11-09", "channel": "phone", "direction": "out" } } }
```

`kind` is one of `met`, `call`, `message`, `meeting`, `email` or `note`. `direction` is `in` (they reached out), `out`
(you did) or `both` (the default); the strength score reads it. Person ids are UUIDs from the search. Over MCP, pass
`format: "json"` for structured answers; the REST routes always answer JSON.

The MCP tool also takes `place` and `globe_note` (a note id the interaction points at). The REST route does not
accept them yet.

## Rules for agents {#rules}

- Search before you add: `people_person_create` answers possible duplicates, and `people_person_merge` folds two
  people into one.
- Never send a message for the member. Draft it, and record it sent only after the member sent it.
- A context card refresh costs one model call under the daily cap; do not refresh in a loop.

## Events {#events}

3 org webhook events, generated from `lib/webhooks/events.ts`. Subscribe an endpoint to them in Settings, Webhooks (see [Webhooks and events](/docs/developers/webhooks)).

| Event | When |
|---|---|
| `people.person.created` | A person became visible to the whole org in Venom People (added as org-wide, or shared with the org): id, name, role, company and the member who owns the record. Never handles, notes, how you met or interactions; a private or team-only person is never sent. |
| `people.person.updated` | An org-wide person in Venom People changed: the same short fields as when it was added. |
| `people.person.removed` | An org-wide person is no longer visible to the org: archived, merged into another, or made private or team-only again. Its id only. |

`workspace_change_list` covers notes and issues only, not People. To keep another system in step with a member's
people, poll `GET /api/v1/people` and `GET /api/v1/people/followups` with that member's own key.

## REST routes {#rest}

The REST twin: 136 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)).

**/people**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people` | Search or list people you know and people shared with you | `people_person_search` |
| POST | `/api/v1/people` | Add a person, optionally with the first interaction | `people_person_create` |
| GET | `/api/v1/people/{person}` | Read a person | `people_person_get` |
| PATCH | `/api/v1/people/{person}` | Change one of your people | `people_person_update` |

**/people/reach**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/reach` | Whom to reach for a topic in a territory: your own people ranked by fit, seniority and reachability, each with a route and why | `people_reach_search` |

**/people/events**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/events` | List events, with how many of your people you met at each | `people_event_list` |
| POST | `/api/v1/people/events` | Add a conference or meetup | `people_event_create` |

**/people/controversy**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PUT | `/api/v1/people/controversy/setting` | Owners and admins: turn the public controversy check on or off (off deletes stored matches) | `people_controversy_set` |
| GET | `/api/v1/people/controversy` | People with a possible or confirmed CancelPeople.com match | `people_controversy_list` |
| GET | `/api/v1/people/{person}/controversy` | What CancelPeople.com reports about a person, summarised, with things to watch out for | `people_controversy_get` |
| POST | `/api/v1/people/{person}/controversy/run` | Run the public controversy check for a person now | `people_controversy_run` |
| POST | `/api/v1/people/{person}/controversy/decide` | Same person (confirmed) or Not this person (dismissed) for a possible CancelPeople.com match | `people_controversy_decide` |

**/people/signals**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/signals/setting` | People signals: on or off, the gear and its model, caps, today's spend and how many people have a result | `people_signalsetting_get` |
| PUT | `/api/v1/people/signals/setting` | Owners and admins: change People signals' settings | `people_signalsetting_set` |
| GET | `/api/v1/people/{person}/signals` | A person's signals: the call, strengths, weaknesses and a score per indicator, or insufficient data | `people_signal_get` |
| POST | `/api/v1/people/{person}/signals/run` | Assess a person now, within the caps | `people_signal_run` |

**/people/ai**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/ai/setting` | People's daily AI limit and today's spend against it and each feature's own daily cap, and the gear People's AI runs on with every gear it may use | `people_aisetting_get` |
| PUT | `/api/v1/people/ai/setting` | Owners and admins: change People's daily AI limit, its gear or the out-of-credit fallback | `people_aisetting_set` |

**/people/classify**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/classify/setting` | People classification: on or off, focus, taxonomy, gear, caps, schedule and today's spend | `people_classifier_get` |
| PUT | `/api/v1/people/classify/setting` | Owners and admins: change People classification's settings | `people_classifier_set` |
| GET | `/api/v1/people/classify/runs` | The latest classification runs with their people, calls, cost and why they stopped | `people_classifier_history` |
| POST | `/api/v1/people/classify/runs` | Estimate (dry_run) or start a classification run, classify one person, or continue a run | `people_classify_run` |
| GET | `/api/v1/people/classify/corrections` | Your classification corrections: what the model said and what you chose | `people_correction_list` |
| GET | `/api/v1/people/classify/quality` | Override rate per field over 30 days, without and with corrections as examples | `people_quality_get` |
| GET | `/api/v1/people/classify/proposals` | Proposed new sector, persona and opportunity values | `people_proposal_list` |
| POST | `/api/v1/people/classify/proposals` | Estimate (dry_run) or run one scan for new category values | `people_taxonomy_propose` |
| POST | `/api/v1/people/classify/proposals/{proposal}/accept` | Owners and admins: add a proposed value to its list | `people_proposal_accept` |
| POST | `/api/v1/people/classify/proposals/{proposal}/dismiss` | Owners and admins: dismiss a proposed value for good | `people_proposal_dismiss` |
| POST | `/api/v1/people/classify/tags` | Preview (dry_run) or add tags from classifications; never removes a tag | `people_autotag_apply` |

**/people/classification**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PUT | `/api/v1/people/{person}/classification` | Set fields of a person's classification by hand (null clears one) | `people_classification_set` |

**/people/enrichment**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/enrichment/setting` | People enrichment: on or off, the providers in order (what each is sent), the daily cap and today's spend | `people_enricher_get` |
| PUT | `/api/v1/people/enrichment/setting` | Owners and admins: turn enrichment on or off, pick providers in order, set the daily cap, store or remove PDL and Apollo keys | `people_enricher_set` |
| POST | `/api/v1/people/enrichment/runs` | Enrich many of your people: start a run (people) or continue one (run); answers progress and cost | `people_enrichment_run` |
| GET | `/api/v1/people/enrichment/next` | Your people most worth enriching next | `people_enrichment_next` |
| GET | `/api/v1/people/{person}/enrichment` | A person's pending enrichment suggestions and photo candidates | `people_enrichment_get` |
| DELETE | `/api/v1/people/{person}/enrichment` | Dismiss a person's pending enrichment suggestions | `people_enrichment_dismiss` |
| POST | `/api/v1/people/{person}/enrichment/apply` | Apply some or all enrichment suggestions, and optionally a photo candidate | `people_enrichment_apply` |

**/people/today**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/today/find` | Find your own people for a request (one bounded model exchange over the People search tools, else a word search), each with a why line | `people_today_find` |
| GET | `/api/v1/people/today/settings` | Your settings for People's Today | `people_todaysetting_get` |
| PUT | `/api/v1/people/today/settings` | Change your settings for People's Today | `people_todaysetting_set` |
| POST | `/api/v1/people/today/notes` | Save how reaching out (or a meeting) went as an interaction with an outcome, then the next step (one bounded model call, else rules) | `people_todaynote_create` |

**/people/briefs**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/briefs` | Your standing briefs and their plans | `people_brief_list` |
| POST | `/api/v1/people/briefs` | Save a request as a standing brief for the day's picks | `people_brief_create` |
| PATCH | `/api/v1/people/briefs/{brief}` | Change, pause or resume a standing brief | `people_brief_update` |
| DELETE | `/api/v1/people/briefs/{brief}` | Delete a standing brief | `people_brief_delete` |

**/people/downvotes**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/downvotes` | Your people marked not yet, with reason and date | `people_downvote_list` |
| POST | `/api/v1/people/downvotes` | Mark one of your people not yet: left out of Today for some days, with a reason | `people_downvote_set` |
| DELETE | `/api/v1/people/downvotes/{person}` | Undo not yet for one of your people | `people_downvote_delete` |

**/people/next-steps**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/next-steps` | The next step a note proposed, by step or the newest for a person | `people_nextstep_get` |
| POST | `/api/v1/people/next-steps/{step}/apply` | Apply a next step, or change its action or date | `people_nextstep_apply` |
| POST | `/api/v1/people/next-steps/{step}/undo` | Undo an applied next step | `people_nextstep_undo` |

**/people/overnight**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/overnight` | Your overnight queue: picks with route, why line and draft; your saved Reach views' nightly switches; last night's numbers | `people_overnight_list` |
| POST | `/api/v1/people/overnight/picks/{pick}` | Act on an overnight pick: edit the draft, log it sent (once), skip, not yet, or redraft | `people_overnight_update` |
| POST | `/api/v1/people/overnight/runs` | Run your nightly Reach views now, under the same limits | `people_overnight_run` |

**/people/outreach**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/outreach/reservations` | Reserve one message to one of your people on one channel: every rule checked, a cap slot held for 30 minutes | `people_outreach_reserve` |
| POST | `/api/v1/people/outreach/reservations/{reservation}/send` | Send a reserved message through Venom Comms as you (or hold it for approval, or draft it, as the bot's settings say) | `people_outreach_send` |
| POST | `/api/v1/people/outreach/reservations/{reservation}/outcome` | Say how a send from a bot's own computer went: sent, failed or needs_owner (once) | `people_outreach_mark_sent` |
| POST | `/api/v1/people/outreach/drafts` | Leave a message as a draft in your overnight queue (nothing is sent) | `people_outreach_draft` |
| GET | `/api/v1/people/outreach` | What was reserved, drafted and sent, newest first | `people_outreach_list` |

**/people/views**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PATCH | `/api/v1/people/views/{view}` | Switch a saved Reach view to run every night, or off, and set how many it picks | `people_view_update` |

**/people/intro-asks**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/intro-asks` | Your intro asks (and colleague requests) with state, age, drafts, nudges due, deal and send-through-Venom status | `people_introask_list` |
| POST | `/api/v1/people/intro-asks` | Draft an intro ask to one of your contacts (template, no model), or drafts in bulk for up to 50 of your people, optionally on a Funnel deal | `people_introask_create` |
| PATCH | `/api/v1/people/intro-asks/{ask}` | Edit, rewrite, link to a deal or record what happened to an intro ask (sent, nudged, agreed, introduced, declined, no_reply, dropped) | `people_introask_update` |
| POST | `/api/v1/people/intro-asks/{ask}/send` | Send the draft ask or the due nudge to the connector through Venom Comms (one message per call, the outreach rules apply) | `people_introask_send` |
| PUT | `/api/v1/people/intro-asks/settings` | Your one-line pitch for intro blurbs and the name drafts sign with | `people_introsetting_set` |

**/people/meetings**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/meetings/sync` | Your Granola meetings sync: connected, on or off, tasks mode, last run and error, open review items | `people_meetingsync_get` |
| PUT | `/api/v1/people/meetings/sync` | Turn your meetings sync on or off, or choose create or suggest for action items | `people_meetingsync_set` |
| POST | `/api/v1/people/meetings/sync/runs` | Run your Granola meetings sync now | `people_meetingsync_run` |
| GET | `/api/v1/people/meetings/history` | Your calendar accounts and where each one's import of past meetings is | `people_meetinghistory_get` |
| POST | `/api/v1/people/meetings/history/runs` | Import the last 24 months of meetings from one calendar account, or from all of them | `people_meetinghistory_run` |
| GET | `/api/v1/people/meetings/reviews` | The meetings review queue: attendees without an email, suggested action items, people from ended calendar meetings who are not in People | `people_meetingreview_list` |
| GET | `/api/v1/people/meetings` | Your meetings from the last day and a half to a week ahead, with their people | `people_meeting_list` |
| POST | `/api/v1/people/meetings/{meeting}/people` | Attach, confirm or detach a person on one of your meetings | `people_meeting_link` |
| POST | `/api/v1/people/meetings/reviews/{review}` | Accept, create or dismiss one review item | `people_meetingreview_decide` |

**/people/meeting-briefs**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/meeting-briefs` | The brief for a person, or for every person in one of your meetings | `people_meetingbrief_get` |
| POST | `/api/v1/people/meeting-briefs/talking-points` | Three talking points for a person, each citing a fact (one model call under the AI limit) | `people_meetingbrief_draft` |

**/people/note-changes**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/note-changes/{change}/apply` | Apply one change a meeting note proposed | `people_notechange_apply` |
| POST | `/api/v1/people/note-changes/{change}/dismiss` | Dismiss one change a meeting note proposed | `people_notechange_dismiss` |

**/people/capture**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/capture` | Draft people from text, a card photo or a vCard, or save drafts (confirm) | `people_capture_create` |

**/people/bulk**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/bulk` | Change many of your people at once: tags, circle, cadence, company, location, seniority, country, gender, sector, delete to the trash or restore; it says who it skipped | `people_person_bulk_update` |

**/people/share**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/share` | Share a person, several, or a whole circle with a team or the org (or take sharing back) | `people_person_share` |

**/people/network**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/network` | Who knows someone at a company or topic: your people and what colleagues shared, with warm-intro paths | `people_network_search` |
| GET | `/api/v1/people/network/paths/{person}` | Warm-intro paths to a person, ranked by the colleague's strength | `people_intro_path` |

**/people/intros**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/intros` | Intro requests asked of you and sent by you | `people_intro_list` |
| POST | `/api/v1/people/intros` | Ask the colleague who knows a shared person for an intro | `people_intro_request` |
| POST | `/api/v1/people/intros/{request}` | Accept, decline, draft, withdraw or close as introduced an intro request | `people_intro_respond` |

**/people/import**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/import` | Import contacts from a file's text (Google, vCard, LinkedIn, HubSpot, Pipedrive CSV, WhatsApp, Telegram); read-only until confirm | `people_import_run` |

**/people/graph**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/graph` | Your network as a graph: you, your people, their companies, and the links between | `people_graph_get` |

**/people/know-who**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/know-who` | Who you know at a company, from a school, in a place, or who worked in a country | `people_know_who` |

**/people/employers**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PUT | `/api/v1/people/employers` | Record where you have worked (LinkedIn's Positions.csv) | `people_employer_set` |

**/people/employments**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| DELETE | `/api/v1/people/employments/{employment}` | Remove a past employer from a person | `people_employment_delete` |
| POST | `/api/v1/people/{person}/employments` | Link a person to a company with a role and dates | `people_employment_create` |

**/people/trips**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/trips` | Your upcoming trips | `people_trip_list` |
| POST | `/api/v1/people/trips` | Add a trip | `people_trip_create` |
| DELETE | `/api/v1/people/trips/{trip}` | Delete a trip | `people_trip_delete` |

**/people/attachments**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/attachments/{attachment}` | One image, file or link kept with a person | `people_attachment_get` |
| PATCH | `/api/v1/people/attachments/{attachment}` | Rename an attachment or change its note | `people_attachment_update` |
| DELETE | `/api/v1/people/attachments/{attachment}` | Delete an image, file or link kept with one of your people | `people_attachment_delete` |
| GET | `/api/v1/people/{person}/attachments` | The images, files and links kept with a person | `people_attachment_list` |
| POST | `/api/v1/people/{person}/attachments` | Keep a link or a file with one of your people: a file by upload_id (after the PUT), a public file_url, or small base64 | `people_attachment_add` |

**/people/images**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/images/{image}` | An image kept with a person: name, type, size, pixel size and a short-lived download URL | `people_image_get` |
| DELETE | `/api/v1/people/images/{image}` | Delete an image kept with one of your people | `people_image_delete` |
| GET | `/api/v1/people/{person}/images` | The images kept with a person | `people_image_list` |
| POST | `/api/v1/people/{person}/images` | Keep an image with one of your people: an upload_id (after the PUT), a public url, or small base64 | `people_image_add` |
| POST | `/api/v1/people/images/uploads` | Prepare a one-time upload URL for a picture's raw bytes (an image, a photo, a card to capture or a file to attach) | `people_image_prepare` |
| POST | `/api/v1/people/{person}/images/read` | Read a person's kept images into suggestions for their profile (saved only with apply all) | `people_image_read` |

**/people/interactions**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PATCH | `/api/v1/people/interactions/{interaction}` | Edit an interaction you logged | `people_interaction_update` |
| DELETE | `/api/v1/people/interactions/{interaction}` | Delete an interaction you logged | `people_interaction_delete` |
| GET | `/api/v1/people/{person}/interactions` | A person's interactions, newest first | `people_interaction_list` |
| POST | `/api/v1/people/{person}/interactions` | Log an interaction with one of your people | `people_interaction_create` |

**/people/relationships**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| DELETE | `/api/v1/people/relationships/{relationship}` | Remove a relationship between two of your people | `people_relationship_delete` |
| GET | `/api/v1/people/{person}/relationships` | A person's links to other people and their companies over time | `people_relationship_list` |
| POST | `/api/v1/people/{person}/relationships` | Link a person to another: knows, colleague, introduced by, reports to, family, partner, investor in, or your own label | `people_relationship_create` |

**/people/companies**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/companies/{company}` | Read a company and the people there you may see | `people_company_get` |
| PATCH | `/api/v1/people/companies/{company}` | Change a company | `people_company_update` |
| GET | `/api/v1/people/companies` | List companies, with people there now and ever | `people_company_list` |

**/people/followups**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/followups/{followup}` | Mark a follow-up done or sent, or snooze or dismiss it | `people_followup_done` |
| PATCH | `/api/v1/people/followups/{followup}` | Replace a follow-up's draft text | `people_followup_update` |
| POST | `/api/v1/people/followups/{followup}/snooze` | Snooze a follow-up for some days (kept as not yet, with a reason) | `people_followup_snooze` |
| POST | `/api/v1/people/followups/{followup}/dismiss` | Dismiss a follow-up: not yet for some days, with a reason | `people_followup_dismiss` |
| POST | `/api/v1/people/followups/{followup}/send` | Record that you sent a follow-up yourself (Venom sends nothing) | `people_followup_send` |
| GET | `/api/v1/people/followups` | Today's follow-ups: the five people to reach out to, with reasons and drafts | `people_followup_list` |
| POST | `/api/v1/people/followups/draft` | Draft a follow-up message with channel links (you send it), or add_only: add a person to today | `people_followup_draft` |

**/people/card**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/{person}/card` | Rewrite a person's context card now | `people_card_refresh` |

**/people/rating**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/{person}/rating` | Rate a person: hot, warm, later or skip | `people_person_rate` |

**/people/circle**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| PUT | `/api/v1/people/{person}/circle` | Set a person's circle and cadence | `people_person_circle_set` |

**/people/merge**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/{keep}/merge` | Merge a duplicate into this person | `people_person_merge` |

**/people/photo**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/{person}/photo` | A person's photo: name, type, size, pixel size and a short-lived download URL | `people_image_get` |
| PUT | `/api/v1/people/{person}/photo` | Set a person's photo: an upload_id (after the PUT), a public url (or an enrichment candidate), or small base64 | `people_person_photo_set` |

**/people/enrich**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/{person}/enrich` | Ask the org's enrichment providers about a person; answers suggestions with sources (nothing is saved) | `people_person_enrich` |

**/people/links**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/{person}/links` | Why a person is connected to others: shared company, school, event, place, topic and more, with every reason | `people_link_list` |

**/people/suggestions**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/{person}/suggestions` | Links worth adding: same company, same event, the introducer named in how you met (nothing is saved) | `people_suggestion_list` |

**/people/debrief**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/debrief` | List events to debrief, show an event's cards, rate people met there | `people_debrief_run` |

**/people/circles**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/people/circles` | Your circles with cadences, or one person's strength with the reasons | `people_circle_list` |
| PATCH | `/api/v1/people/circles` | Change a circle's cadence, or a person's circle and cadence | `people_circle_update` |

**/people/recall**

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | `/api/v1/people/recall` | Who do I know who…: an answer from your people with citations | `people_recall_ask` |

## MCP tools {#tools}

135 tools: 50 read, 85 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `people_aisetting_get` | People's AI limit, gear and today's spend | read | `people:read` | `GET /api/v1/people/ai/setting` |
| `people_aisetting_set` | Change People's AI limit or gear | write | `people:write` | `PUT /api/v1/people/ai/setting` |
| `people_attachment_add` | Keep a link or a file with a person | write | `people:write` | `POST /api/v1/people/{person}/attachments` |
| `people_attachment_delete` | Delete an attachment | write (destructive) | `people:write` | `DELETE /api/v1/people/attachments/{attachment}` |
| `people_attachment_get` | Read one attachment | read | `people:read` | `GET /api/v1/people/attachments/{attachment}` |
| `people_attachment_list` | List what is kept with a person | read | `people:read` | `GET /api/v1/people/{person}/attachments` |
| `people_attachment_update` | Rename an attachment or change its note | write | `people:write` | `PATCH /api/v1/people/attachments/{attachment}` |
| `people_autotag_apply` | Add tags from classifications | write | `people:write` | `POST /api/v1/people/classify/tags` |
| `people_brief_create` | Save a standing brief | write | `people:write` | `POST /api/v1/people/briefs` |
| `people_brief_delete` | Delete a standing brief | write (destructive) | `people:write` | `DELETE /api/v1/people/briefs/{brief}` |
| `people_brief_list` | List standing briefs | read | `people:read` | `GET /api/v1/people/briefs` |
| `people_brief_update` | Change a standing brief | write | `people:write` | `PATCH /api/v1/people/briefs/{brief}` |
| `people_capture_create` | Capture people from a note, photo or contact file | write | `people:write` | `POST /api/v1/people/capture` |
| `people_card_refresh` | Refresh a context card | write | `people:write` | `POST /api/v1/people/{person}/card` |
| `people_circle_list` | List circles | read | `people:read` | `GET /api/v1/people/circles` |
| `people_circle_update` | Change a circle or cadence | write | `people:write` | `PATCH /api/v1/people/circles` |
| `people_classification_set` | Set a person's classification by hand | write | `people:write` | `PUT /api/v1/people/{person}/classification` |
| `people_classifier_get` | People classification settings | read | `people:read` | `GET /api/v1/people/classify/setting` |
| `people_classifier_history` | People classification runs | read | `people:read` | `GET /api/v1/people/classify/runs` |
| `people_classifier_set` | Change People classification settings | write | `people:write` | `PUT /api/v1/people/classify/setting` |
| `people_classify_run` | Run People classification | write | `people:write` | `POST /api/v1/people/classify/runs` |
| `people_company_get` | Read a company | read | `people:read` | `GET /api/v1/people/companies/{company}` |
| `people_company_list` | List companies | read | `people:read` | `GET /api/v1/people/companies` |
| `people_company_update` | Change a company | write | `people:write` | `PATCH /api/v1/people/companies/{company}` |
| `people_controversy_decide` | Same person or not: decide a possible match | write | `people:write` | `POST /api/v1/people/{person}/controversy/decide` |
| `people_controversy_get` | A person's public controversy result | read | `people:read` | `GET /api/v1/people/{person}/controversy` |
| `people_controversy_list` | People flagged by the public controversy check | read | `people:read` | `GET /api/v1/people/controversy` |
| `people_controversy_run` | Check a person now | write | `people:write` | `POST /api/v1/people/{person}/controversy/run` |
| `people_controversy_set` | Turn the public controversy check on or off | write (destructive) | `people:write` | `PUT /api/v1/people/controversy/setting` |
| `people_correction_list` | Your classification corrections | read | `people:read` | `GET /api/v1/people/classify/corrections` |
| `people_debrief_run` | Debrief an event | write | `people:write` | `POST /api/v1/people/debrief` |
| `people_downvote_delete` | Undo not yet | write (destructive) | `people:write` | `DELETE /api/v1/people/downvotes/{person}` |
| `people_downvote_list` | List not-yet people | read | `people:read` | `GET /api/v1/people/downvotes` |
| `people_downvote_set` | Mark a person not yet | write | `people:write` | `POST /api/v1/people/downvotes` |
| `people_employer_set` | Record your own employers | write | `people:write` | `PUT /api/v1/people/employers` |
| `people_employment_create` | Link a person to a company | write | `people:write` | `POST /api/v1/people/{person}/employments` |
| `people_employment_delete` | Remove a person's past employer | write (destructive) | `people:write` | `DELETE /api/v1/people/employments/{employment}` |
| `people_enricher_get` | People enrichment settings | read | `people:read` | `GET /api/v1/people/enrichment/setting` |
| `people_enricher_set` | Change People enrichment settings | write | `people:write` | `PUT /api/v1/people/enrichment/setting` |
| `people_enrichment_apply` | Apply enrichment suggestions | write | `people:write` | `POST /api/v1/people/{person}/enrichment/apply` |
| `people_enrichment_dismiss` | Dismiss enrichment suggestions | write (destructive) | `people:write` | `DELETE /api/v1/people/{person}/enrichment` |
| `people_enrichment_get` | A person's enrichment suggestions | read | `people:read` | `GET /api/v1/people/{person}/enrichment` |
| `people_enrichment_next` | Who to enrich next | read | `people:read` | `GET /api/v1/people/enrichment/next` |
| `people_enrichment_run` | Enrich many people | write | `people:write` | `POST /api/v1/people/enrichment/runs` |
| `people_event_create` | Add an event | write | `people:write` | `POST /api/v1/people/events` |
| `people_event_list` | List events | read | `people:read` | `GET /api/v1/people/events` |
| `people_followup_dismiss` | Dismiss a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}/dismiss` |
| `people_followup_done` | Finish, snooze or drop a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}` |
| `people_followup_draft` | Draft a follow-up | write | `people:write` | `POST /api/v1/people/followups/draft` |
| `people_followup_list` | Today's follow-ups | read | `people:read` | `GET /api/v1/people/followups` |
| `people_followup_send` | Record a follow-up as sent | write | `people:write` | `POST /api/v1/people/followups/{followup}/send` |
| `people_followup_snooze` | Snooze a follow-up | write | `people:write` | `POST /api/v1/people/followups/{followup}/snooze` |
| `people_followup_update` | Edit a follow-up's draft | write | `people:write` | `PATCH /api/v1/people/followups/{followup}` |
| `people_graph_get` | Your network as a graph | read | `people:read` | `GET /api/v1/people/graph` |
| `people_image_add` | Keep an image with a person | write | `people:write` | `POST /api/v1/people/{person}/images` |
| `people_image_delete` | Delete a person's image | write (destructive) | `people:write` | `DELETE /api/v1/people/images/{image}` |
| `people_image_get` | See a person's image or photo | read | `people:read` | `GET /api/v1/people/images/{image}` (+1) |
| `people_image_list` | List a person's images | read | `people:read` | `GET /api/v1/people/{person}/images` |
| `people_image_prepare` | Prepare a picture upload | write | `people:write` | `POST /api/v1/people/images/uploads` |
| `people_image_read` | Read a person's images into their profile | write | `people:write` | `POST /api/v1/people/{person}/images/read` |
| `people_import_run` | Import contacts from a file's text | write | `people:write` | `POST /api/v1/people/import` |
| `people_interaction_create` | Log an interaction | write | `people:write` | `POST /api/v1/people/{person}/interactions` |
| `people_interaction_delete` | Delete an interaction | write (destructive) | `people:write` | `DELETE /api/v1/people/interactions/{interaction}` |
| `people_interaction_list` | List interactions | read | `people:read` | `GET /api/v1/people/{person}/interactions` |
| `people_interaction_update` | Edit an interaction | write | `people:write` | `PATCH /api/v1/people/interactions/{interaction}` |
| `people_intro_list` | Intro requests | read | `people:read` | `GET /api/v1/people/intros` |
| `people_intro_path` | Warm-intro paths to a person | read | `people:read` | `GET /api/v1/people/network/paths/{person}` |
| `people_intro_request` | Ask a colleague for an intro | write | `people:write` | `POST /api/v1/people/intros` |
| `people_intro_respond` | Answer an intro request | write | `people:write` | `POST /api/v1/people/intros/{request}` |
| `people_introask_create` | Draft an intro ask | write | `people:write` | `POST /api/v1/people/intro-asks` |
| `people_introask_list` | List your intro asks | read | `people:read` | `GET /api/v1/people/intro-asks` |
| `people_introask_send` | Send an intro ask or nudge through Venom | write (destructive) | `people:write` | `POST /api/v1/people/intro-asks/{ask}/send` |
| `people_introask_update` | Change or move an intro ask | write | `people:write` | `PATCH /api/v1/people/intro-asks/{ask}` |
| `people_introsetting_set` | Set your pitch for intro blurbs | write | `people:write` | `PUT /api/v1/people/intro-asks/settings` |
| `people_know_who` | Who do I know at, from or in | read | `people:read` | `GET /api/v1/people/know-who` |
| `people_link_list` | Why people are connected | read | `people:read` | `GET /api/v1/people/{person}/links` |
| `people_meeting_link` | Change who is in a meeting | write | `people:write` | `POST /api/v1/people/meetings/{meeting}/people` |
| `people_meeting_list` | List your meetings | read | `people:read` | `GET /api/v1/people/meetings` |
| `people_meetingbrief_draft` | Suggest talking points | read | `people:read` | `POST /api/v1/people/meeting-briefs/talking-points` |
| `people_meetingbrief_get` | Brief before a meeting | read | `people:read` | `GET /api/v1/people/meeting-briefs` |
| `people_meetinghistory_get` | Past meetings import status | read | `people:read` | `GET /api/v1/people/meetings/history` |
| `people_meetinghistory_run` | Import past meetings | write | `people:write` | `POST /api/v1/people/meetings/history/runs` |
| `people_meetingreview_decide` | Decide a review item | write | `people:write` | `POST /api/v1/people/meetings/reviews/{review}` |
| `people_meetingreview_list` | Meetings review queue | read | `people:read` | `GET /api/v1/people/meetings/reviews` |
| `people_meetingsync_get` | Meetings sync status | read | `people:read` | `GET /api/v1/people/meetings/sync` |
| `people_meetingsync_run` | Sync meetings now | write | `people:write` | `POST /api/v1/people/meetings/sync/runs` |
| `people_meetingsync_set` | Change the meetings sync | write | `people:write` | `PUT /api/v1/people/meetings/sync` |
| `people_network_search` | Who knows someone at … | read | `people:read` | `GET /api/v1/people/network` |
| `people_nextstep_apply` | Apply a next step | write | `people:write` | `POST /api/v1/people/next-steps/{step}/apply` |
| `people_nextstep_get` | Next step for a person | read | `people:read` | `GET /api/v1/people/next-steps` |
| `people_nextstep_undo` | Undo a next step | write (destructive) | `people:write` | `POST /api/v1/people/next-steps/{step}/undo` |
| `people_notechange_apply` | Apply a change from a meeting note | write | `people:write` | `POST /api/v1/people/note-changes/{change}/apply` |
| `people_notechange_dismiss` | Dismiss a change from a meeting note | write | `people:write` | `POST /api/v1/people/note-changes/{change}/dismiss` |
| `people_outreach_draft` | Leave a message as a draft | write | `people:write` | `POST /api/v1/people/outreach/drafts` |
| `people_outreach_list` | What was reserved, drafted and sent | read | `people:read` | `GET /api/v1/people/outreach` |
| `people_outreach_mark_sent` | Say how a computer send went | write | `people:write` | `POST /api/v1/people/outreach/reservations/{reservation}/outcome` |
| `people_outreach_reserve` | Reserve a message to someone | write | `people:write` | `POST /api/v1/people/outreach/reservations` |
| `people_outreach_send` | Send a reserved message | write (destructive) | `people:write` | `POST /api/v1/people/outreach/reservations/{reservation}/send` |
| `people_overnight_list` | The overnight queue | read | `people:read` | `GET /api/v1/people/overnight` |
| `people_overnight_run` | Run my night now | write | `people:write` | `POST /api/v1/people/overnight/runs` |
| `people_overnight_update` | Act on an overnight pick | write | `people:write` | `POST /api/v1/people/overnight/picks/{pick}` |
| `people_person_bulk_update` | Change many people at once | write (destructive) | `people:write` | `POST /api/v1/people/bulk` |
| `people_person_circle_set` | Set a person's circle | write | `people:write` | `PUT /api/v1/people/{person}/circle` |
| `people_person_create` | Add a person | write | `people:write` | `POST /api/v1/people` |
| `people_person_enrich` | Enrich a person | write | `people:write` | `POST /api/v1/people/{person}/enrich` |
| `people_person_get` | Read a person | read | `people:read` | `GET /api/v1/people/{person}` |
| `people_person_merge` | Merge two people | write (destructive) | `people:write` | `POST /api/v1/people/{keep}/merge` |
| `people_person_photo_set` | Set a person's photo | write | `people:write` | `PUT /api/v1/people/{person}/photo` |
| `people_person_rate` | Rate a person | write | `people:write` | `POST /api/v1/people/{person}/rating` |
| `people_person_search` | Search people | read | `people:read` | `GET /api/v1/people` |
| `people_person_share` | Share people with a team or the org | write | `people:write` | `POST /api/v1/people/share` |
| `people_person_update` | Change a person | write | `people:write` | `PATCH /api/v1/people/{person}` |
| `people_proposal_accept` | Accept a proposed category | write | `people:write` | `POST /api/v1/people/classify/proposals/{proposal}/accept` |
| `people_proposal_dismiss` | Dismiss a proposed category | write | `people:write` | `POST /api/v1/people/classify/proposals/{proposal}/dismiss` |
| `people_proposal_list` | Proposed classification categories | read | `people:read` | `GET /api/v1/people/classify/proposals` |
| `people_quality_get` | People classification quality | read | `people:read` | `GET /api/v1/people/classify/quality` |
| `people_reach_search` | Whom to reach for a topic | read | `people:read` | `GET /api/v1/people/reach` |
| `people_recall_ask` | Who do I know who… | read | `people:read` | `POST /api/v1/people/recall` |
| `people_relationship_create` | Link two people | write | `people:write` | `POST /api/v1/people/{person}/relationships` |
| `people_relationship_delete` | Remove a relationship | write (destructive) | `people:write` | `DELETE /api/v1/people/relationships/{relationship}` |
| `people_relationship_list` | List a person's links | read | `people:read` | `GET /api/v1/people/{person}/relationships` |
| `people_signal_get` | A person's signals | read | `people:read` | `GET /api/v1/people/{person}/signals` |
| `people_signal_run` | Assess a person now | write | `people:write` | `POST /api/v1/people/{person}/signals/run` |
| `people_signalsetting_get` | People signals settings | read | `people:read` | `GET /api/v1/people/signals/setting` |
| `people_signalsetting_set` | Change People signals settings | write | `people:write` | `PUT /api/v1/people/signals/setting` |
| `people_suggestion_list` | Suggest links | read | `people:read` | `GET /api/v1/people/{person}/suggestions` |
| `people_taxonomy_propose` | Look for new classification categories | write | `people:write` | `POST /api/v1/people/classify/proposals` |
| `people_today_find` | Find people to reach out to | read | `people:read` | `POST /api/v1/people/today/find` |
| `people_todaynote_create` | Save how it went | write | `people:write` | `POST /api/v1/people/today/notes` |
| `people_todaysetting_get` | Today settings | read | `people:read` | `GET /api/v1/people/today/settings` |
| `people_todaysetting_set` | Change Today settings | write | `people:write` | `PUT /api/v1/people/today/settings` |
| `people_trip_create` | Add a trip | write | `people:write` | `POST /api/v1/people/trips` |
| `people_trip_delete` | Delete a trip | write (destructive) | `people:write` | `DELETE /api/v1/people/trips/{trip}` |
| `people_trip_list` | List upcoming trips | read | `people:read` | `GET /api/v1/people/trips` |
| `people_view_update` | Switch a Reach view to nightly | write | `people:write` | `PATCH /api/v1/people/views/{view}` |

## Related {#related}

- [Venom People for agents](/docs/cloud/people-mcp.md): what each tool does, in one table.
- [Venom People](/docs/cloud/people.md): who sees what, circles and the AI limits.
- [Capture](/docs/cloud/people-capture.md), [Import](/docs/cloud/people-import.md), [Keep your network warm](/docs/cloud/people-keep-warm.md) and [The network](/docs/cloud/people-network.md).
- [The REST twin](/docs/developers/rest.md) and [Venom for agents](/docs/cloud/workspace-mcp.md): the shared envelope and errors.
- [Authentication and scopes](/docs/developers/auth.md) and [Errors, limits and pagination](/docs/developers/conventions.md).
