API Reference
Needle API
Needle Agents API Reference (v1).
Programmatic access to leads, campaigns, LinkedIn, Instagram, and more. Every endpoint uses the same base URL and Bearer authentication.
For AI agents, start at the onboarding skill, connect at the MCP server, or read the full index at /llms-full.txt.
Features
Leads
Build lead lists from LinkedIn and the Places API.
Campaigns
Run multi-channel, multi-account outreach on LinkedIn and Instagram.
Drafts
See drafted messages waiting for a person to review them before they send.
Search people and run outreach from connected accounts.
Reach people on Instagram from connected accounts.
Events
Search activity across campaigns, leads, and connected accounts.
Places
Find companies and locations to source lists.
Connected Accounts
Connect LinkedIn and Instagram accounts to send from.
Suppressions
Keep people and companies you should not contact off the list.
Webhooks
Receive every outbound event at your own URL as it happens.
Compose
Preview a message before you send it.
Files
Store a private file (upload bytes, or copy a public URL), list files in the workspace, then attach one to a LinkedIn message or InMail.
Base URL
All routes start with /api/v1.
Authentication
Authenticate every request with Authorization: Bearer sk-ndl-…. Create a key in the dashboard under API keys. Each key is bound to one user and one workspace.
curl https://needle.app/api/v1/me \ -H "Authorization: Bearer sk-ndl-…" \ -H "Content-Type: application/json"
Response codes
Successful requests return 2xx. Client errors return 4xx. Server errors return 5xx.
2xx | Success |
400 | Bad request |
401 | Unauthorized. Missing or invalid API key. |
403 | Forbidden |
404 | Not found |
422 | Invalid request payload |
5xx | Server error |
Me
Connected accounts
Leads
Campaigns
Drafts
Events
- GETGet a LinkedIn profile
- POSTRemoved LinkedIn people search
- POSTSearch LinkedIn people
- POSTSearch Sales Navigator people
- POSTSend a LinkedIn message
- GETList messages in a conversation
- GETList sent invitations
- POSTSend a connection invitation
- DELWithdraw an invitation
- GETList first-degree connections
- GETGet a LinkedIn company
- GETList jobs posted by a company
- POSTSearch LinkedIn jobs
- GETGet a LinkedIn job
- POSTSearch LinkedIn companies
- POSTSearch LinkedIn posts
- GETList posts by a person or company
- GETGet a LinkedIn post
- GETList comments on a post
- POSTComment on a post
- GETList reactions on a post
- POSTReact to a post
- POSTSend a Sales Navigator InMail
- GETGet remaining InMail credits
- GETList conversations
- GETList followers
- GETList followed accounts
- GETList received invitations
- POSTAccept or decline a received invitation
- GETList LinkedIn search parameters
- GETGet an Instagram profile
- GETGet the connected account profile
- POSTSend an Instagram message
- POSTReact to an Instagram message
- GETList Instagram conversations
- GETList messages in a conversation
- GETList the participants of a conversation
- GETList the posts of an account
- POSTPublish an Instagram post
- GETGet an Instagram post
- GETList the comments on a post
- POSTComment on a post
- GETList the likes on a post
- POSTLike a post
- GETList followers
- GETList followed accounts
- POSTFollow an Instagram user
- DELUnfollow an Instagram user