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

# Lookup: create a segment from a description

> Natural-language description → applied filter segment

Creates a segment from a natural-language description. Used by the Chrome extension's "Create stream from search" flow.

The AI pipeline maps the description to canonical filter labels via the audit-079 auto-approve workflow (LLM-proposed labels are materialized into the controlled vocabulary, then re-mapped, in one call).

## Body

| Field              | Type              | Description                                                                                 |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------- |
| `description`      | string (required) | Natural-language description, max 1000 chars                                                |
| `trackedAccountId` | number            | Optional - assign the new segment to this tracked account via the default-stream chokepoint |

## Response

```json theme={null}
{
  "segment": {
    "id": 12,
    "name": null,
    "description": "AI founders building developer tools"
  },
  "assignment": {
    "assigned": true,
    "alreadyAssigned": false,
    "position": 0
  },
  "assignError": null
}
```

`assignment` is null when `trackedAccountId` was not supplied. `assignError` is populated on cap-exceeded / not-found / account-inactive.

## Errors

| Code                            | HTTP | When                                                  |
| ------------------------------- | ---- | ----------------------------------------------------- |
| `no_filters_matched`            | 400  | LLM couldn't extract any filters from the description |
| `cap_exceeded` (in assignError) | -    | Tier cap of segments-per-account exceeded             |

## Auth

Bearer API key (extension or manual).