Skip to main content
POST
/
api
/
v2
/
segments
Create a segment
curl --request POST \
  --url https://api.example.com/api/v2/segments
Creates a new segment. The returned id can be passed as segmentId in a pairs[] entry on POST /api/v2/streams or PATCH /api/v2/streams/. If you’d rather author the segment inline as part of stream creation, pass an inline segment: {...} object in the pair instead.

​
Body

FieldTypeDescription
descriptionstring (required)What this segment is looking for
namestringOptional display name
genderValuesarraye.g. ["female"]
appliedSearchFiltersobjecte.g. { "job_role": ["Founder", "CEO"], "skill": ["AI/ML"] }
followerCountTiersarraye.g. ["10k_to_100k"]

​
Example

curl -X POST https://www.catchthegoodones.com/api/v2/segments \
  -H "Authorization: Bearer ctgo_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "AI founders building developer tools",
    "appliedSearchFilters": { "job_role": ["Founder", "CEO"], "skill": ["AI/ML"] }
  }'

​
Response

{ "id": 12, "userFacingId": "seg_12" }

​
Errors

CodeHTTPWhen
orphan_label400appliedSearchFilters contained labels with no canonical match. Response includes orphans[] listing them.

​
Auth

Bearer or session cookie.