# Leads & Pipelines

> **TL;DR for agents:** Pipelines: `/api/pipelines`. Leads: `/api/leads`, kanban view: `/api/leads/kanban/:pipelineId`. Move leads with `POST /api/leads/:id/move`. Hide technical stages with `PATCH /api/pipelines/:pipelineId/stages/:stageId { isHidden: true }`.

## Pipelines list (with stages and lead counts)

Scope: `pipelines:read`. Each stage carries `_count.leads` and `isHidden`.

```bash
curl -s "https://api.live-direct-marketing.online/api/pipelines?includeHidden=1" \
  -H "Authorization: Bearer $LDM_KEY"
```

## Create lead

Scope: `leads:write`. Required: `pipelineId`, `stageId`, `title`. Optional: `amount`, `currency`, `companyId`, `contactId`.

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/leads" \
  -H "Authorization: Bearer $LDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId":"<uuid>","stageId":"<uuid>",
    "title":"Acme — pilot","amount":50000,"currency":"USD",
    "companyId":"<uuid>","contactId":"<uuid>"
  }'
```

## Move lead between stages

Scope: `leads:write`. Body: `{ "stageId": "<uuid>" }`. Server records the move in stage history.

```bash
curl -s -X POST "https://api.live-direct-marketing.online/api/leads/$LEAD_ID/move" \
  -H "Authorization: Bearer $LDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stageId":"<next-stage-uuid>"}'
```

## Hide technical stages from kanban

Scope: `pipelines:write`. Useful when a pipeline has 15+ stages (auto-classification, scoring, etc.) — hide the noise so the kanban shows only the main funnel.

```bash
curl -s -X PATCH "https://api.live-direct-marketing.online/api/pipelines/$PIPELINE_ID/stages/$STAGE_ID" \
  -H "Authorization: Bearer $LDM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isHidden":true}'
```