> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchthegoodones.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a segment

> Create a reusable segment (filter set) that can be added to streams later

Creates a new segment. The returned `id` can be passed as `segmentId` in a `pairs[]` entry on [POST /api/v2/streams](/api-reference/create-stream) or [PATCH /api/v2/streams/{id}](/api-reference/update-stream).

If you'd rather author the segment inline as part of stream creation, pass an inline `segment: {...}` object in the pair instead.

## Body

| Field                  | Type              | Description                                                   |
| ---------------------- | ----------------- | ------------------------------------------------------------- |
| `description`          | string (required) | What this segment is looking for                              |
| `name`                 | string            | Optional display name                                         |
| `genderValues`         | array             | e.g. `["female"]`                                             |
| `appliedSearchFilters` | object            | e.g. `{ "job_role": ["Founder", "CEO"], "skill": ["AI/ML"] }` |
| `followerCountTiers`   | array             | e.g. `["10k_to_100k"]`                                        |

## Example

```bash theme={null}
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

```json theme={null}
{ "id": 12, "userFacingId": "seg_12" }
```

## Errors

| Code           | HTTP | When                                                                                                         |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------ |
| `orphan_label` | 400  | `appliedSearchFilters` contained labels with no canonical match. Response includes `orphans[]` listing them. |

## Auth

Bearer or session cookie.