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

Segments API

Segments endpoints exposed by the Devotel CPaaS API Base path: /api/v1 Endpoint count: 4

title: “AI-proposed segments and ad-hoc exports” description: “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). 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)

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

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)
}

Build a segment from a natural-language description (AI)

POST /api/v1/contacts/segments/autopilot

Translate a natural-language audience description into structured Orbit segment rules and return them together with a live preview match-count and sample contacts, in a single round-trip. The proposed rules are constrained to the segmentation engine’s allowlisted fields, validated with a dry-run before the preview, and returned in both the dashboard’s flat rule shape and the normalised FilterAst the engine consumes — so the operator’s “Create” click needs no second translation. Requires the contacts:write scope (owner / admin / developer). Returns 503 SERVICE_UNAVAILABLE when the AI backend is not configured for the platform; callers should fall back to the manual segment builder.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

string

required

Natural-language description of the audience to build (e.g. “customers in Germany who opened an email in the last 30 days”). The handler asks the LLM to translate it into structured segment rules constrained to the segmentation engine’s allowlisted fields.

integer

Maximum number of sample contacts returned in preview.sample_contacts. Keeps the payload bounded — the dashboard renders only the first 10.

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": "string"
}'

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": "string"
}),
})
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": "string"
})
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": "string"
}`)))
	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": "string"
}.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": "string"
}
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"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "status": 0,
    "details": "string"
  },
  "meta": {
    "request_id": "req_sample",
    "timestamp": "1970-01-01T00:00:00.000Z"
  }
}

Auto-suggest segments

POST /api/v1/segments/auto-suggest

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/segments/auto-suggest" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/segments/auto-suggest', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/segments/auto-suggest", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/segments/auto-suggest", bytes.NewBuffer([]byte(`{}`)))
	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/segments/auto-suggest')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/segments/auto-suggest');
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
{}
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"
  }
}

Export an ad-hoc audience as CSV

POST /api/v1/segments/export.csv

Resolve an ad-hoc audience — an unsaved segment filter AST, the same shape the segment builder and POST /api/v1/segments/auto-suggest produce — live against the tenant’s contacts and download the matched rows as an RFC-4180 CSV attachment, without first persisting or materialising a segment. PII columns (phone, email) honour the caller’s role + reveal context. Requires the contacts:write scope (owner / admin / developer). Hard-capped at 50,000 rows; a truncated export sets the X-Export-Truncated: true response header. The saved-segment equivalent is GET /api/v1/contacts/segments/{id}/export.csv.

string

string (enum: true|false)

cURL

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

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/segments/export.csv', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/segments/export.csv", headers=headers, json={})
print(r.json())

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(`{}`)))
	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/segments/export.csv')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/segments/export.csv');
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
{}
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"
  }
}

Build a clicked-cohort segment from tracked link clicks

POST /api/v1/segments/from-clicks

Resolve the recipient contacts that clicked a tracked short link (link_id) or any link in a campaign (campaign_id) and materialise them as a static contact segment for retargeting. Click engagement is captured as a point-in-time snapshot (auto_refresh = false). Optionally narrow to a recency window with window_days. Requires the contacts:write scope (owner / admin / developer).

string

string (enum: true|false)

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/segments/from-clicks" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/segments/from-clicks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
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/segments/from-clicks", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/segments/from-clicks", bytes.NewBuffer([]byte(`{}`)))
	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/segments/from-clicks')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.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/segments/from-clicks');
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
{}
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"
  }
}

API Reference

All Endpoints

Segments API

Segments API

title: “AI-proposed segments and ad-hoc exports” description: “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

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.

Describe a segment (AI autopilot)

Export an ad-hoc audience as CSV

Build a segment from a natural-language description (AI)

Auto-suggest segments

Export an ad-hoc audience as CSV

Build a clicked-cohort segment from tracked link clicks

​Segments API

​title: “AI-proposed segments and ad-hoc exports” description: “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

​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.

​Describe a segment (AI autopilot)

​Export an ad-hoc audience as CSV

​Build a segment from a natural-language description (AI)

​Auto-suggest segments

​Export an ad-hoc audience as CSV

​Build a clicked-cohort segment from tracked link clicks

Segments API

title: “AI-proposed segments and ad-hoc exports” description: “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

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.

Describe a segment (AI autopilot)

Export an ad-hoc audience as CSV

Build a segment from a natural-language description (AI)

Auto-suggest segments

Export an ad-hoc audience as CSV

Build a clicked-cohort segment from tracked link clicks