# 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](/agent-onboarding/SKILL.md), connect at the [MCP server](/docs/mcp/introduction), or read the full index at [`/llms-full.txt`](/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. - **LinkedIn**: Search people and run outreach from connected accounts. - **Instagram**: 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 `https://needle.app/api/v1` 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. ```bash 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 ## Endpoints ### Me - [Get the authenticated user](/docs/api-reference/get-me) ### Connected accounts - [List connected accounts](/docs/api-reference/list-connected-accounts) - [Get a connected account](/docs/api-reference/get-connected-account) - [Update a connected account](/docs/api-reference/update-connected-account) - [Delete a connected account](/docs/api-reference/delete-connected-account) - [List connected account events](/docs/api-reference/list-connected-account-events) - [List connected account limits](/docs/api-reference/list-connected-account-limits) - [Override a limit](/docs/api-reference/update-connected-account-limit) - [Reset a limit to defaults](/docs/api-reference/reset-connected-account-limit) - [List connected account tasks](/docs/api-reference/list-connected-account-tasks) ### Leads - [List leads](/docs/api-reference/list-leads) - [Create a lead](/docs/api-reference/create-lead) - [Create or update a lead](/docs/api-reference/upsert-lead) - [Create leads in bulk](/docs/api-reference/create-leads) - [Update leads in bulk](/docs/api-reference/update-leads) - [Delete leads in bulk](/docs/api-reference/delete-leads) - [Get a lead](/docs/api-reference/get-lead) - [Update a lead](/docs/api-reference/update-lead) - [Delete a lead](/docs/api-reference/delete-lead) - [List lead events](/docs/api-reference/list-lead-events) - [List lead tasks](/docs/api-reference/list-lead-tasks) ### Campaigns - [List campaigns](/docs/api-reference/list-campaigns) - [Create a campaign](/docs/api-reference/create-campaign) - [Get a campaign](/docs/api-reference/get-campaign) - [Update a campaign](/docs/api-reference/update-campaign) - [Archive a campaign](/docs/api-reference/archive-campaign) - [Get campaign stats](/docs/api-reference/get-campaign-stats) - [List campaign events](/docs/api-reference/list-campaign-events) - [List campaign tasks](/docs/api-reference/list-campaign-tasks) - [List campaign leads](/docs/api-reference/list-campaign-leads) - [Enroll leads](/docs/api-reference/enroll-campaign-leads) - [Stop leads in a campaign in bulk](/docs/api-reference/stop-campaign-leads) - [Stop a lead in a campaign](/docs/api-reference/remove-campaign-lead) ### Drafts - [List drafts](/docs/api-reference/list-drafts) ### Events - [Search events](/docs/api-reference/search-events) ### LinkedIn - [Get a LinkedIn profile](/docs/api-reference/get-linkedin-profile) - [Removed LinkedIn people search](/docs/api-reference/removed-linkedin-people-search) - [Search LinkedIn people](/docs/api-reference/search-linkedin-classic-people) - [Search Sales Navigator people](/docs/api-reference/search-linkedin-sales-navigator-people) - [Send a LinkedIn message](/docs/api-reference/send-linkedin-message) - [List messages in a conversation](/docs/api-reference/list-linkedin-conversation-messages) - [List sent invitations](/docs/api-reference/list-linkedin-invitations) - [Send a connection invitation](/docs/api-reference/send-linkedin-invitation) - [Withdraw an invitation](/docs/api-reference/withdraw-linkedin-invitation) - [List first-degree connections](/docs/api-reference/list-linkedin-relations) - [Get a LinkedIn company](/docs/api-reference/get-linkedin-company) - [List jobs posted by a company](/docs/api-reference/list-linkedin-company-jobs) - [Search LinkedIn jobs](/docs/api-reference/search-linkedin-jobs) - [Get a LinkedIn job](/docs/api-reference/get-linkedin-job) - [Search LinkedIn companies](/docs/api-reference/search-linkedin-companies) - [Search LinkedIn posts](/docs/api-reference/search-linkedin-posts) - [List posts by a person or company](/docs/api-reference/list-linkedin-posts) - [Get a LinkedIn post](/docs/api-reference/get-linkedin-post) - [List comments on a post](/docs/api-reference/list-linkedin-post-comments) - [Comment on a post](/docs/api-reference/comment-on-linkedin-post) - [List reactions on a post](/docs/api-reference/list-linkedin-post-reactions) - [React to a post](/docs/api-reference/react-to-linkedin-post) - [Send a Sales Navigator InMail](/docs/api-reference/send-linkedin-in-mail) - [Get remaining InMail credits](/docs/api-reference/get-linkedin-in-mail-balance) - [List conversations](/docs/api-reference/list-linkedin-conversations) - [List followers](/docs/api-reference/list-linkedin-followers) - [List followed accounts](/docs/api-reference/list-linkedin-following) - [List received invitations](/docs/api-reference/list-linkedin-received-invitations) - [Accept or decline a received invitation](/docs/api-reference/respond-to-linkedin-invitation) - [List LinkedIn search parameters](/docs/api-reference/list-linkedin-search-parameters) ### Instagram - [Get an Instagram profile](/docs/api-reference/get-instagram-profile) - [Get the connected account profile](/docs/api-reference/get-instagram-account-profile) - [Send an Instagram message](/docs/api-reference/send-instagram-message) - [React to an Instagram message](/docs/api-reference/react-to-instagram-message) - [List Instagram conversations](/docs/api-reference/list-instagram-conversations) - [List messages in a conversation](/docs/api-reference/list-instagram-conversation-messages) - [List the participants of a conversation](/docs/api-reference/list-instagram-conversation-participants) - [List the posts of an account](/docs/api-reference/list-instagram-posts) - [Publish an Instagram post](/docs/api-reference/create-instagram-post) - [Get an Instagram post](/docs/api-reference/get-instagram-post) - [List the comments on a post](/docs/api-reference/list-instagram-post-comments) - [Comment on a post](/docs/api-reference/comment-on-instagram-post) - [List the likes on a post](/docs/api-reference/list-instagram-post-reactions) - [Like a post](/docs/api-reference/like-instagram-post) - [List followers](/docs/api-reference/list-instagram-followers) - [List followed accounts](/docs/api-reference/list-instagram-following) - [Follow an Instagram user](/docs/api-reference/follow-instagram-user) - [Unfollow an Instagram user](/docs/api-reference/unfollow-instagram-user) ### Places - [Search places](/docs/api-reference/search-places) - [Get a place](/docs/api-reference/get-place) ### Compose - [Preview an AI-composed message](/docs/api-reference/compose-preview) ### Files - [List files](/docs/api-reference/list-files) - [Create a file upload](/docs/api-reference/create-file-upload) - [Delete a file](/docs/api-reference/delete-file) - [Create a file preview URL](/docs/api-reference/create-file-access-url) ### Suppressions - [List suppressions](/docs/api-reference/list-suppressions) - [Create suppressions](/docs/api-reference/create-suppressions) - [Check people and companies against the suppression list](/docs/api-reference/check-suppressions) - [Delete a suppression](/docs/api-reference/delete-suppression) ### Webhooks - [List webhooks](/docs/api-reference/list-webhooks) - [Create a webhook](/docs/api-reference/create-webhook) - [Get a webhook](/docs/api-reference/get-webhook) - [Update a webhook](/docs/api-reference/update-webhook) - [Delete a webhook](/docs/api-reference/delete-webhook)