REST API

The REST API exposes the same operations as the MCP server, for automation tools (n8n, Make, Zapier, Clay) and scripts.

• Base URL: https://api.useneedle.net/v1
• OpenAPI 3.1: https://api.useneedle.net/v1/openapi.json
• Auth: Authorization: Bearer ndl_live_… from Settings → API & MCP

curl https://api.useneedle.net/v1/leads?since=24h -H "Authorization: Bearer ndl_live_…"

Responses are JSON. Lists page with limit (max 50) and cursor: pass next_cursor from one page as cursor for the next, with the same filters.

Endpoints

Each operation's inputs and outputs are in the OpenAPI document. Leads use the needle.lead.v1 shape, the same as the lead object in webhook events.

Searches

POST /v1/search waits up to 25 seconds. A finished search answers 200 with up to 10 leads per network (40 in total). A longer one answers 202 with status: "running" and a Location: /v1/searches/{id} header; poll it about every 30 seconds (free) until status is complete or failed. A search's status and leads stay available from GET /v1/searches/{id} for 24 hours; the leads also stay in your Needle dashboard.

Headers

• X-RateLimit-Limit, X-RateLimit-Remaining: the per-key minute window. A 429 adds Retry-After and X-RateLimit-Reset.
• X-Needle-Quota-Monthly-Remaining: API calls left this month, after a counted call.

API keys

Create a key in Settings → API & MCP. Keys start with ndl_live_ and are shown once, so store them like a password. Revoke a key there at any time; it stops working within seconds. Keys never expire unless you pick an expiry (30, 90 or 365 days).

Each key has scopes. All are ticked by default; untick some for a narrower key, for example a read-only dashboard key.

Send the key as Authorization: Bearer ndl_live_… (or x-api-key: ndl_live_…). Never put it in a URL.

Plans and limits

The API and MCP server are included in the Growth and Scale plans.

• Every tool call counts as one API call, only when it succeeds. get_usage and get_search are free.
• search counts when it starts. A search that fails or is interrupted later does not use one of your daily searches, but the call that started it stays counted.
• Monthly calls reset on the 1st at 00:00 UTC. Daily searches and drafts reset at 00:00 UTC.
• One search runs at a time per account.
• Needle never posts for you. Reply drafts are text for you to review and post yourself.

Errors

Errors have a stable code you can rely on:

{ "error": { "code": "daily_limit_exceeded", "message": "No searches left today. Searches reset at 00:00 UTC." } }