API: Suggestions
Cross-tenant customer suggestion board, voting, comments, and personal activity metadata.
На этой странице
Раздел собран из спецификации OpenAPI продукта: 7 метод(ов). Поверхность — query-api (основной API, база /api/v1). Все методы требуют аутентификации.
Методы раздела
/suggestions List the public suggestion board (cloud only)
Cross-tenant board: the feed returns suggestions written by customers of other organisations. Responses carry the author's display name only — never an organisation or an email address. Moderated (hidden) suggestions never appear here. Not mounted on-prem.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
status необязателен | Query | enum(new, planned, done, rejected) | |
tag необязателен | Query | string | Tag slug from GET /suggestions/meta. |
q необязателен | Query | string | Case-insensitive substring match over title and body. |
sort необязателен | Query | enum(new, top) | По умолчанию "new". |
cursor необязателен | Query | string | |
limit необязателен | Query | integer | По умолчанию 20. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | One page of the board, newest or highest scoring first | SuggestionPage |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 422 | Request failed validation (code=validation_failed) | Error |
/suggestions Publish a suggestion to the board (any role, cloud only)
Publishes immediately, without pre-moderation. Every organisation role may post, viewer included: feedback should not depend on a seat. Exempt from the trial write-gate — a customer whose trial expired is exactly the one with something to say. Limited to 5 per user per day.
Тело запроса application/json , обязательно
| Поле | Тип | Описание |
|---|---|---|
title обязательно | string | |
body обязательно | string | |
tag_ids необязательно | array<integer (int64)> |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 201 | The published card | Suggestion |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 422 | Request failed validation (code=validation_failed) | Error |
| 429 | Rate limit (code=rate_limited) or plan quota exceeded (code=quota_exceeded). On ingest operations a live trial that exhausted its total event cap answers code=trial_quota_exceeded instead of quota_exceeded. Заголовки: Retry-After.
| Error |
/suggestions/{id} Read one suggestion with its discussion
A suggestion hidden by moderation answers 404 for everyone except its own author, who instead sees it flagged with the reason — otherwise the author concludes the text was lost and writes it again.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int64) | Suggestion id. |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | The suggestion, its tags and its comment thread | SuggestionDetail |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 404 | Resource not found (code=not_found) | Error |
/suggestions/{id}/comments Comment on a suggestion (any role, cloud only)
Limited to 30 per user per day. Hidden suggestions accept no comments.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int64) | Suggestion id. |
Тело запроса application/json , обязательно
| Поле | Тип | Описание |
|---|---|---|
body обязательно | string |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 201 | The published comment | SuggestionComment |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 404 | Resource not found (code=not_found) | Error |
| 422 | Request failed validation (code=validation_failed) | Error |
| 429 | Rate limit (code=rate_limited) or plan quota exceeded (code=quota_exceeded). On ingest operations a live trial that exhausted its total event cap answers code=trial_quota_exceeded instead of quota_exceeded. Заголовки: Retry-After.
| Error |
/suggestions/{id}/vote Cast, change or withdraw a vote
Idempotent: repeating the same value does not accumulate. `0` withdraws the vote entirely rather than recording a neutral one.
Параметры
| Имя | Где | Тип | Описание |
|---|---|---|---|
id обязателен | Путь | integer (int64) | Suggestion id. |
Тело запроса application/json , обязательно
| Поле | Тип | Описание |
|---|---|---|
value обязательно | enum(-1, 0, 1) |
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | The card with its updated score | Suggestion |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
| 404 | Resource not found (code=not_found) | Error |
| 422 | Request failed validation (code=validation_failed) | Error |
| 429 | Rate limit (code=rate_limited) or plan quota exceeded (code=quota_exceeded). On ingest operations a live trial that exhausted its total event cap answers code=trial_quota_exceeded instead of quota_exceeded. Заголовки: Retry-After.
| Error |
/suggestions/meta Tags, per-status counts and the personal unread badge
One request for everything the board's sidebar and the shell's badge need. `badge` counts team replies and status changes on suggestions the caller authored or voted on since their last visit — deliberately not overall board activity, which would always be non-zero and mean nothing personally.
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 200 | Board metadata for the calling user | SuggestionsMeta |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
/suggestions/seen Clear the unread badge for the calling user
Ответы
| Код | Что означает | Тело |
|---|---|---|
| 204 | Badge cleared | пусто |
| 401 | Missing or invalid credentials (code=unauthorized) | Error |
Источник раздела — docs/api/openapi.yaml репозитория продукта,
версия API 1.0.0, OpenAPI 3.0.3,
снимок e2d62cf449b2.
Расхождение снимка со спецификацией роняет сборку документации.