API-пайплайн: поиск по графу

Индекс: API-пайплайны — индекс

Цель: находить карточки по ключевым словам или по смыслу с уточнением по типу карточки, рубрике, стране, месту и расстоянию; или сразу переходить к карточке по её ссылке, @handle или nonce.

Для публичных результатов токен не нужен; с токеном вы получаете также то, что видно вошедшим пользователям, и то, чем поделились с вами.

Шаги

1. Поиск.

POST /v0/search/graph
{"query": "bike repair", "card_type": "project", "page": 1, "limit": 20,
 "filters": {"exclude_terms": ["casino"]}}
→ {"hits": [{"card_type": "project", "nonce": "470000000000000001", "title": "…", "snippet": "…",
             "rubrics": […], "location": {"nonce": "…", "title": "Lisbon", "geo": {"lat": 38.72, "lon": -9.14}}, …}],
   "total_hits": 101, "page": 1, "total_pages": 6}

• /v0/search/graph сочетает ключевые слова и смысл (движок по умолчанию); /v0/search/graph/keyword ищет только по словам; /v0/search/graph/vector — только по смыслу. Тело и ответ одинаковые.
• query обрезается до 200 символов; он может быть пустым, если поиск сужает фильтр или card_type.
• page начинается с 1; limit 1–100 (по умолчанию 20).
• card_type: project, article, post, telegram_group, agenda, board, doc, sheet, rubric, workspace, …
• card_types: несколько типов сразу, подходит любой из них, например ["project", "article"]; можно вместе с card_type.
• Найденные рубрики несут can_mark для вошедших: можно ли отмечать карточки этой рубрикой: API-пайплайн: рубрики для карточек, раздел B3.

2. Сузьте поиск через filters.

Nonce рубрик и мест: поиск {"query": "dentist", "card_type": "rubric", "filters": {"kind": "tag"}}; места по названию города или страны: API-пайплайн: добавить свои Telegram-группы, найти группы по ключевому слову, месту или рубрике, проверить их и подключить к кампании (часть B).

3. Поиск внутри рабочего пространства: добавьте "workspace": "<workspace nonce>".

4. Переход к карточке по ссылке.

GET /v0/graph/resolve/@example-handle
→ {"card_type": "project", "nonce": "470000000000000001", "handle": "example-handle", "title": "…", "kind": null}

Принимает nonce, @handle или handle без @; переименованный handle тоже находится. Затем откройте карточку через GET /v0/graph/{type}s/{nonce}.

5. Выбор среди своих карточек (нужен токен):

GET /v0/accessible/cards?type=project&type=workspace&q=trip&limit=30
→ {"items": [{"nonce": "…", "card_type": "workspace", "title": "Trip ideas", "source": "owned",
              "permissions": {"read": true, "write": true, "execute": true}, "snippet": "…", …}],
   "next_cursor": "…"}

Карточки, которыми вы владеете, плюс карточки, которыми поделились с вами, с вашими правами на каждую. q ищет по заголовкам на всех языках и по handle; nonce, @handle или ссылка https://cabi.chat/… в q ставят эту карточку первой. type обязателен (повторите его или перечислите через запятую, до 20); limit до 100; листайте с cursor=<next_cursor>, пока он не станет null.

Правила

• 400 unknown filter: <key>, malformed filter: <key>, filters must be an object, workspace must be a nonce, workspace not found.
• resolve: 404, если карточка неизвестна или вам не видна.
• accessible/cards: 400 type is required, bad card type: …, bad cursor; 401 без токена.

Поверхность API