---
title: "Create Segment"
method: POST
path: "/api/app-auto-gtm/segments"
tags: ["AppAutoGtm"]
---

# Create Segment

`POST /api/app-auto-gtm/segments`

Create a segment under the user's project, prefilled by the same LLM
pass the funnel uses for its n=6 explore generation.

The user supplies only the segment name; the LLM produces pain /
use_case / criteria / example_clients tailored to that label using the
project's domain, description and competitors. On any LLM failure
(timeout, parse error, empty response) we surface a 500 — better that
the user retries than ends up with an unusable empty segment that
blocks the sender downstream.

## Cookies

- `ex_access` string, nullable
- `ex_org` string, nullable

## Request body

- CreateSegmentRequest — Body for POST /segments — manual segment creation from the sidebar. All ICP fields are filled in afterwards via PATCH on the Docs tab; this endpoint only seeds an empty row so the user has somewhere to type into.
  - `project_id` integer, required
  - `name` string, required

## Response `200`

Successful Response

- SegmentBrief
  - `name` string, required — Short campaign / segment name (2-4 words)
  - `pain` string — Core pain this ICP has (max ~10 words)
  - `use_case` string — What this ICP does with the product (max ~15 words)
  - `keywords` string — Comma-separated search keywords (5-8, lowercase, 1-3 words each)
  - `positive_criterias` string[] — Positive signals identifying this buyer (qualitative, 3-5 words each)
  - `negative_criterias` string[] — Disqualifying signals — look-alikes that are NOT a fit
  - `example_clients` string[] — Recognizable example companies that fit this ICP
  - `decision_maker` string — Who to reach at the prospect, framed by responsibility
  - `target_geo` string — Target geographies — country names, comma-separated
  - `target_company_size` string — Target company size — free-text prompt, e.g. "mid-market and enterprise", "startups under 50"
  - `id` integer, required
  - `description` string, required
  - `context` string
  - `daily_limit_usd` integer, required
  - `paused` boolean
  - `agent_turn_running` boolean
  - `instructions` string
  - `followup_instructions` string
  - `language` string
  - `target_url` string, nullable
  - `email_templates` object
  - `email_templates_version` integer
  - `updated_at` string
  - `people_count` integer
  - `preview_leads` PreviewLead[]
    - `id` string, required
    - `first_name` string, required
    - `last_name` string, required
    - `company` string, required
    - `lead_country_iso_2` string
    - `company_geo_country` string
    - `lead_headline` string
    - `profile_photo_url` string
    - `company_logo_url` string
    - `company_domain` string
  - `cached_previews` GeneratedEmailPayload[]
    - `id` string, required
    - `segment_id` integer, required
    - `lead_id` string, required
    - `touch_number` integer, required
    - `email_templates_version` integer, required
    - `subject` string, required
    - `body` string, required
    - `lead_first_name` string
    - `lead_last_name` string
    - `lead_company_name` string
    - `language_used` string
    - `language_reason` string
    - `highlights` EmailHighlight[]
      - `text` string, required
      - `kind` 'research' | 'ab_test' | 'instructions' | 'playbook', required
      - `title` string, required
      - `explanation` string, required
      - `sources` string[]
    - `cache_hit` boolean
  - `schedule` SegmentSchedule
    - `timezone` string, nullable
    - `working_hours` string, nullable
    - `days` string[], nullable
    - `use_system_schedule` boolean, nullable
    - `days_source` 'system' | 'user', nullable
    - `days_backfill_version` integer, nullable
  - `followup_rules` SegmentFollowupRules
    - `max_touches` integer
    - `delay_days` integer, nullable
    - `stop_on_reply` boolean, nullable
  - `report_frequency` string, nullable
  - `status_display` StatusDisplay — Unified status display object added to every client-facing segment payload. Computed once in _build_status_display; emitted as `status_display` on the wire. All legacy fields (status, paused, status_reason, agent_turn_running) remain unchanged for deploy-skew safety. Iteration-1 value vocabulary: not_started | searching | review | outreach | paused | budget_paused | listening | resuming | archived | error (`budget_paused` is the display-only $0-budget mask — see _ZERO_BUDGET_MASKED_STATES; no matching lifecycle status exists.)
    - `value` string, required
    - `label` string, required
    - `tone` string, required
    - `animated` boolean, required
    - `hint` string, required
    - `detail` string, required
    - `manual_start_blocked` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/explee/apis/explee-api.md) · [All operations](https://skmtc.dev/explee/apis/explee-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/explee/explee-api/revisions/f169bc6e9447/schema)