> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI-proposed segments and ad-hoc exports

> Describe an audience in plain language and get structured rules plus a live preview; or pull an unsaved FilterAst out to CSV without persisting a segment.

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

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.