> For the complete documentation index, see [llms.txt](https://boundaryai.gitbook.io/boundaryai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boundaryai.gitbook.io/boundaryai-docs/api-and-webhooks/concepts-and-naming.md).

# Concepts & naming

The API speaks the same model as the product. Four nouns cover almost everything:

| API noun (recommended) | In the product                                                        | What it is                                                                  |
| ---------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `feedback_group`       | [Feedback Group](/boundaryai-docs/feedback-groups/feedback-groups.md) | The project container. Everything about one programme lives in one group.   |
| `source`               | A source inside a group                                               | One stream of feedback: a survey, an upload, a connector, or your API push. |
| `field`                | A question / column                                                   | One typed slot on a source: open text, NPS, a scale, metadata.              |
| item (in `content`)    | A response / comment                                                  | One piece of feedback pushed into a field.                                  |

Two product concepts you'll meet in responses:

* **Monitors** ([Custom Monitoring](/boundaryai-docs/analysing-your-feedback/custom-monitoring.md)) appear in analysis reads under the `flags` key, and the related webhook event is `flag.raised`. Those are the *legacy wire names* for what the product now calls monitors; the payloads are stable so existing subscribers don't break.
* **Analysis** is asynchronous. Pushing returns immediately; themes, sentiment, and monitor matches appear when the analysis pass completes (subscribe to `analysis.completed` rather than polling).

***

### Already integrated on the older vocabulary?

Integrations built when the API spoke `survey_series` / `survey` / `question` keep working unchanged: those routes (`/survey_series/create`, `/survey/create`, `/content/push`, and friends) hit the same handlers as the routes documented here, are fully supported, and are covered by the [compatibility policy](/boundaryai-docs/api-and-webhooks/changelog.md). We keep them out of the reference so there's exactly one documented way to do each thing. The mapping, should you read old code: `survey_series` = feedback group, `survey` = source, `question` = field.

***

### Field types

When creating a source, each field takes a `field_type`:

| Type          | Use for                                                                    |
| ------------- | -------------------------------------------------------------------------- |
| `DEPTH_TEXT`  | Long free text: the field the AI analyses for themes, sentiment, monitors. |
| `TEXT`        | Short free text: names, one-liners.                                        |
| `NPS`         | The 0-10 likelihood-to-recommend score.                                    |
| `RATING`      | A numeric scale with your own bounds (`min_value` / `max_value`).          |
| `SCQ` / `MCQ` | Single / multiple choice (`field_options`).                                |
| `METADATA`    | Context for segmentation (region, plan, agent); imported but not analysed. |

Names are case-insensitive, and `long_answer` / `short_answer` are accepted as synonyms for `DEPTH_TEXT` / `TEXT`.

The richest analytical signal comes from `DEPTH_TEXT` fields; `METADATA` fields power segmentation in the analysis views, exactly as with [uploads](/boundaryai-docs/bringing-in-your-feedback/uploading-an-existing-dataset.md).

***

### `feedback_type`: tell the platform what the data is

Sources take an optional `feedback_type` (`survey`, `call_transcript`, `app_review`, `support_ticket`, `chat`, `email`, `social_media`, `review`, `other`). It's echoed in listings and helps the platform frame the data correctly. Pick the closest one rather than defaulting everything to `other`.