AI-proposed segments and ad-hoc exports

These two operations serve the campaign desk side of the contacts module — the screen where marketers shape an audience by hand or by prompt and take the rows out. Use the autopilot to translate a natural-language prompt into rules plus a live match-count preview in one round-trip; use the export to pull an unsaved FilterAst into a CSV without persisting anything. Build from a description. POST /api/v1/contacts/segments/autopilot returns operator (the boolean the LLM chose), rules (the flat list the dashboard renders), filters (the normalized FilterAst the segmentation engine consumes — so the following “Create” click needs no second translation), and preview (match_count + sample_contacts).

{
  "data": {
    "operator": "and",
    "rules": [
      { "field": "country", "operator": "equals", "value": "Germany" },
      { "field": "email.opens_last_days", "operator": "lte", "value": 30 }
    ],
    "filters": {
      "op": "AND",
      "conditions": [
        { "field": "country", "operator": "equals", "value": "Germany" },
        { "field": "email.opens_last_days", "operator": "lte", "value": 30 }
      ]
    },
    "preview": {
      "match_count": 1240,
      "sample_contacts": [
        { "id": "ct_9f3a", "name": "Lena Braun", "country": "Germany" }
      ]
    },
    "llm_output_preview": "Proposed rules: country equals Germany AND email.opens_last_days lte 30 ..."
  },
  "meta": {
    "request_id": "req_autopilot",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The proposed rules are constrained to the segmentation engine’s allowlisted fields and engine-dry-run validated before the preview, so a 422 means “try rephrasing” (the response echoes the first 500 chars of the LLM’s raw output). A 503 SERVICE_UNAVAILABLE means the AI backend is not configured for the platform — fall back to the manual segment builder. Both endpoints require the contacts:write scope (owner / admin / developer). Export an unsaved audience. POST /api/v1/segments/export.csv resolves the same FilterAst shape the manual builder produces — a single condition or a nested AND / OR group — live against the tenant’s contacts and returns the matched rows as an RFC-4180 CSV download. PII columns (phone, email) honor the caller’s role and reveal context exactly as the dashboard renders them. A truncated export (past the 50,000-row ceiling, limit-clamped below it) sets the X-Export-Truncated: true response header so you know you got a partial pull.

API Reference

All Endpoints

AI-proposed segments and ad-hoc exports

AI-proposed segments and ad-hoc exports

​AI-proposed segments and ad-hoc exports

AI-proposed segments and ad-hoc exports