AI-proposed segments and ad-hoc exports

{
  "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"
  }
}

{
  "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"
  }
}

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). The Node SDK has no typed helper for this surface; use the generic request() escape hatch shown below — it keeps the { data, meta } envelope identical. Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
}'

Node.js

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", headers=headers, json={
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", bytes.NewBuffer([]byte(`{
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "description": "customers in Germany who opened an email in the last 30 days",
  "preview_limit": 5
}
JSON);
echo curl_exec($ch);

{
  "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.

SDK surface bridge — Translate a natural-language audience into engine-validated rules, or export an unsaved FilterAst out to CSV — both reachable through the SDK escape hatch.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the sandbox key.

Describe a segment (AI autopilot)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "customers in Germany who opened an email in the last 30 days"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "description": "customers in Germany who opened an email in the last 30 days"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", json={
  "description": "customers in Germany who opened an email in the last 30 days"
}, headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/segments/autopilot", bytes.NewBuffer([]byte(`{
  "description": "customers in Germany who opened an email in the last 30 days"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Export an ad-hoc audience as CSV

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/segments/export.csv" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {}
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/segments/export.csv', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "filters": {}
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/segments/export.csv", json={
  "filters": {}
}, headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/segments/export.csv", bytes.NewBuffer([]byte(`{
  "filters": {}
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

API Reference

All Endpoints

AI-proposed segments and ad-hoc exports