nh_live_ tokens under Settings, API & MCP answer 401 on these routes (checked live 2026-11-17). Both are stored on the account: the plugin sends them as HTTP Basic auth, where the email is the username and the key is the password.
Set both before the first call, for example pnpm corsair setup --plugin=nethunt --tenant=acme api_key=<key> email=<you@example.com>, or pass key and email in the plugin options. account.verify confirms the pair works and returns the user behind it.
What to know before you write:
- Folders hold user-defined fields.
folders.listgives the ids, andfolders.fieldsgives the names a create or update may set. There are no fixed columns, so call both before building a field map. - A create and an update take different shapes.
records.createtakes a flatfieldsmap plus a requiredtimeZone, which NetHunt needs to interpret date values.records.updatetakesfieldActions, one entry per field, each able tooverwrite,removeoradd. Combiningoverwritewithremoveis rejected here because NetHunt forbids it. - A delete goes over POST and answers
{}. So does linking a Gmail thread. Both return a small result the plugin derives from the call that succeeded, rather than from a body that carries nothing. records.changesis the only route that reports a delete. Each change lists, per field, the values removed (remove) and added (add), and the user who made it as{ personalName, emailAddress }. It is a change log, not a snapshot history: it has no full before and after values.- Reads page by time, not by offset.
records.recentandrecords.updateddefault their window to 24 hours and take asinceinstant. NetHunt takesfieldNamerepeatedly for one call, which the plugin sends as separate parameters.
- NetHunt sends no error codes. A bad email or key is a 401 with a plain-text body, not JSON. A missing folder or record is a 404 with an empty body. The plugin reads both.
- A 5xx on a write is never retried. NetHunt takes no idempotency key, so a retried create or update can double up. A 5xx on a read is retried twice.
- 16 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the NetHunt CRM API key before the first call: More: API Key
pnpm corsair setup --plugin=nethunt --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
List the folders this account can readWhat’s next
API reference
Every
nethunt.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.