​

Changelog

All notable changes to the Naturalead API are documented here.

​

2026-09-02 — WhatsApp token freshness warning

​

Added

• GET /api/integrations returns whatsappTokenStale and whatsappTokenAgeDays. Meta Embedded Signup tokens last about 60 days; reconnect WhatsApp in Settings to refresh, or sending/receiving may fail.

​

2026-09-01 — Inbound entries

​

Added

• Inbound entries on agent config (inboundEntries): first-touch WhatsApp messages can land on any stage instead of always opening at the start of the journey. Empty condition is the default landing; conditioned entries use the same matcher as stage transitions.
• Flow builder Inbound source node with dashed entry edges.

​

2026-08-20 — Agent Evaluations removed

​

Removed

• Agent Evaluations dashboard (/evaluations), API (/api/evaluations/*), and supporting playground conversation channel used only by the eval harness.
• RBAC permissions evaluations:view and evaluations:manage.
• MongoDB collections evaltests and evalruns (cleaned up via migration 20260820100000-remove-evaluation-data).

​

Unchanged

• Bot Playground (Bot > Playground tab) and Playground Sessions remain available for manual agent testing.

​

2026-08-12 — Stage insights on terminal enter

​

Changed

• Custom Insight Definitions (/api/insight-definitions) and agent insightDefinitionIds allowlists are removed.
• Configure insights on a terminal stage via stages[].stageInsights[] (fieldName, instructions) in the bot flow editor.
• When a conversation enters a terminal stage (no outgoing edges) that has stageInsights, the engine evaluates each field once (full transcript + RAG + existing insights) and upserts into Lead Insights (GET /api/preferences/{leadId}).
• Each evaluation attempt is audited as lead_preference.stage_insight_evaluated (Account Audit) with status (extracted / omitted / rejected_* / error), reason, model, full operator instructions, the evidencePrompt used for judgment (transcript + RAG + existing insights), and a truncated raw model response preview.
• Stage insight evaluator defaults to a stronger model (STAGE_INSIGHT_EVALUATOR_MODEL, else EVAL_JUDGE_MODEL / OPENAI_MODEL, else gpt-5.4).

​

2026-08-10 — Docs playground base URL

​

Changed

• OpenAPI servers now default to https://api.naturalead.ai (localhost kept as a secondary option). Fixes Mintlify “Try It” / base URL showing http://localhost:3001.

​

2026-08-10 — Lead Insights (preferences) public API

​

Added

• Documented Lead Insights under /api/preferences (list / update / delete).
• Insights are the structured key points shown in the conversation UI (topic, preference, confidence) — the recommended CRM sync payload for what a lead shared.
• Dual-auth on /api/preferences so API keys with conversations:view / conversations:edit can access the same endpoints as the dashboard.

​

Notes

• Insights are lead-scoped, not conversation-scoped. Conversation summary is not populated today; prefer GET /api/preferences/{leadId}.
• GET path id is the lead id; PATCH / DELETE path id is the preference document _id.

​

2026-08-09 — Stage-centric home, analytics, and Flow tab

​

Added

• Overview analytics: sessionStatus, avgMessages, completedRate, handedOffRate.
• Daily analytics: replied, handed_off series (alongside deprecated qualification fields).
• Dashboard Journey by stage snapshot (7d) and dedicated Bot Flow tab with viewport-height canvas.

​

Changed

• Analytics UI emphasizes outreach / session / journey — not qualification-rate heroes.
• Campaign analytics table shows reply rate instead of qualification conversion as the primary rate.

​

Deprecated

• Overview qualificationRate / avgMessagesToQualify — still returned for one release; prefer the new fields and /api/analytics/stage-distribution.

​

2026-08-09 — Deprecate agent-level LLM qualification criteria

​

Changed

• Journey outcome is the conversation terminal stage (no outgoing edges). Stage edge conditions / transitionCriteria remain the rules to move between stages.
• Conversation finalize no longer calls LLM evaluateQualification, no longer writes qualificationResult, no longer emits the qualification webhook, and no longer bumps campaign-lead qualified / disqualified from that scorecard.
• Closing messages are stage-aware (terminal stage / max-messages), not a pass/fail boolean.

​

Deprecated

• AgentConfig.qualificationCriteria — ignored by the conversation engine (field kept for one release so old configs still load).
• Conversation qualificationResult — historical rows remain readable; new completes do not write it.
• Outbound webhook event qualification — stop emitting; use stage_transition and status_change (includes currentStageName).
• Agent/overview qualifiedLeads / qualificationRate — prefer stageReach and /api/analytics/stage-distribution.

​

2026-08-09 — Incremental sync via updatedAfter / updatedBefore

​

Added (docs)

• Documented updatedAfter and updatedBefore query params on GET /api/leads and GET /api/conversations.
• Timestamps accept ISO 8601 or Unix epoch (seconds or milliseconds). Filters use strict $gt / $lt on updatedAt.
• Lead updatedAt is bumped when related conversation activity occurs, so lead-list waterfalls see conversation changes.

​

2026-08-09 — Slim lead outreach + journey stage

​

Changed

• Lead status is outreach I/O only: new | contacted. Values qualified and disqualified are no longer valid on leads.
• Journey position is expressed via conversation currentStage / currentStageName (and enriched currentStage on lead list responses), not lead CRM status.
• GET /api/analytics/funnel returns outreach/session steps: new → contacted → replied → handed_off (array of { stage, count }).

​

Added

• GET /api/analytics/stage-distribution — per-agent journey stage counts
• stageReach on GET /api/agent-config/{id}/stats

​

Notes

• Campaign-lead statuses (pending / sent / qualified / …) remain separate from lead outreach status. New completes no longer set campaign qualified/disqualified from the deprecated LLM scorecard.
• Agent stage names such as "qualified" remain valid free-form stage labels in agent configs.

​

2026-03-29 — Initial API Documentation

​

Added

• Public API documentation site at docs.naturalead.ai
• OpenAPI 3.1.0 specifications for all 13 API domains
• Interactive “Try It” playground for every endpoint
• Multi-language code examples (cURL, Python, Node.js)
• Comprehensive guides for common workflows
• Full RBAC permissions matrix documentation
• Rate limit documentation with retry strategies

​

API Domains Documented

• Leads — 13 endpoints for lead CRUD, import, search, and filtering
• Lead Sync — 2 endpoints for bulk create/update/delete
• Conversations — 5 endpoints for AI-driven conversations
• Campaigns — 8 endpoints for batch outreach
• Agent Config — 11 endpoints for AI agent management
• Knowledge Bases — 22 endpoints for documents, crawl jobs, and webhook sources
• Analytics — 5 endpoints for reporting and metrics
• A/B Testing — 7 endpoints for experiment management
• Audit Logs — 2 endpoints for compliance and monitoring
• Integrations — 4 endpoints for channel configuration
• API Keys — 5 endpoints for key lifecycle management
• Accounts & Teams — 7 endpoints for organization management
• Webhooks — 4 inbound webhook endpoints