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

# Segments API

> Segments endpoints exposed by the Devotel CPaaS API

# Segments API

Segments endpoints exposed by the Devotel CPaaS API

**Base path:** `/api/v1`

**Endpoint count:** 2

***

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

<Note>
  `POST /api/v1/contacts/segments/autopilot`
</Note>

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

<ParamField body="description" type="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.
</ParamField>

<ParamField body="preview_limit" type="integer">
  Maximum number of sample contacts returned in `preview.sample_contacts`. Keeps the payload bounded — the dashboard renders only the first 10.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    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"
    }'
    ```

    ```typescript Node.js theme={null}
    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 Python theme={null}
    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())
    ```

    ```go Go theme={null}
    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 Ruby theme={null}
    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 theme={null}
    <?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);
    ```
  </CodeGroup>
</RequestExample>

***

### Export an ad-hoc audience as CSV

<Note>
  `POST /api/v1/segments/export.csv`
</Note>

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

<ParamField body="filters" type="object" required>
  The audience definition — the same FilterAst the segment builder and auto-suggest speak (a single condition or a nested AND/OR group). Validated server-side against the field allowlist + depth cap.
</ParamField>

<ParamField body="limit" type="integer">
  Optional row cap below the 50,000-row hard ceiling (e.g. for a quick sample). Clamped server-side.
</ParamField>

<ParamField body="filename" type="string">
  Optional filename stem for the download. Sanitised so it cannot break the Content-Disposition header.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    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 '{
      "filters": {}
    }'
    ```

    ```typescript Node.js theme={null}
    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({
      "filters": {}
    }),
    })
    console.log(await res.json())
    ```

    ```python Python theme={null}
    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={
      "filters": {}
    })
    print(r.json())
    ```

    ```go Go theme={null}
    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_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")
    	http.DefaultClient.Do(req)
    }
    ```

    ```ruby Ruby theme={null}
    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 = {
      "filters": {}
    }.to_json
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    puts res.body
    ```

    ```php PHP theme={null}
    <?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
    {
      "filters": {}
    }
    JSON);
    echo curl_exec($ch);
    ```
  </CodeGroup>
</RequestExample>

***