# 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.
- **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.
- **Compose**: Preview a message before you send it.

## Base URL

`undefined/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 organization.

```bash
curl undefined/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)

### Leads

- [List leads](/docs/api-reference/list-leads)
- [Create a lead](/docs/api-reference/create-lead)
- [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)

### 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 leads](/docs/api-reference/list-campaign-leads)
- [Enroll leads](/docs/api-reference/enroll-campaign-leads)
- [Stop a lead in a campaign](/docs/api-reference/remove-campaign-lead)
- [List pending approvals](/docs/api-reference/list-pending-approvals)
- [Approve a pending send](/docs/api-reference/approve-pending-task)

### Events

- [Search events](/docs/api-reference/search-events)

### LinkedIn

- [Get a LinkedIn profile](/docs/api-reference/get-linkedin-profile)
- [Search LinkedIn people](/docs/api-reference/search-linkedin-people)
- [Send a LinkedIn message](/docs/api-reference/send-linkedin-message)
- [List messages in a conversation](/docs/api-reference/list-linkedin-conversation-messages)
- [List pending 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)

### Instagram

- [Get an Instagram profile](/docs/api-reference/get-instagram-profile)
- [Send an Instagram message](/docs/api-reference/send-instagram-message)
- [List messages in a conversation](/docs/api-reference/list-instagram-conversation-messages)
- [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)

### 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)