# Kumquat

> Інструментарій креативної команди — база рекламних креативів із фільтрами та node-пайплайн генерації.

## Docs

- [Документація Kumquat](/): Інструментарій креативної команди.

## Посібник

- [Поля картки задачі](/guide/task-and-creative-fields-overview): Що означає кожне поле картки Task, коли воно заповнюється, коли ховається чи блокується — гайд для тих, хто вперше працює з платформою.
- [Статуси задач та блокування полів](/guide/task-statuses-and-naming-lock-overview): Канбан Tasks — статуси, дозволені переходи, автоматизація та які поля редагуються в якому статусі.
- [Неймінг задач і креативів](/guide/creative-naming-overview): Як платформа складає назву задачі та кожної картки креативу — сегмент за сегментом і випадок за випадком.
- [Завантаження файлів у task description](/guide/uploads-overview): Фото і файли вантажаться в S3 через окремий ендпоінт; відео живе на Google Drive.
- [Вигрузка креативів і задач у Google Sheets](/guide/exports-overview): Вибираєте колонки, натискаєте Export — таблиця зʼявляється в Drive, посилання приходить у Slack.
- [Інбокс: сповіщення в Kumquat](/guide/inbox-overview): Що приходить у дзвіночок, коли спливає тост і як вимкнути зайве — у Kumquat чи в Slack.
- [Агент-аналітик: що це і як ним користуватись](/guide/analyst-agent-overview): Пояснення для маркетологів — навіщо потрібен агент-аналітик і як ставити йому питання.
- [Web funnels: колонки й формули](/guide/web-funnels-overview): Як читати сторінку Web funnels — що означає кожна колонка, як вона рахується і чому деякі клітинки порожні.
- [Gdrive-sync: що це і як воно працює](/guide/gdrive-sync-overview): Синхронізація відео, фото та плеєйблів з Google Drive — пояснення без технічних деталей.
- [Гарячі клавіші](/guide/hotkeys-overview): Як відкривати таски — у вікні поверх дошки, на всю сторінку чи в новій вкладці — і всі клавіші, які розуміє Kumquat.

## Kumquat API

- [Kumquat API](/api)

### Analytics

- [Creative Analytics Schema](/api/analytics/creative-analytics-schema-api-v1-analytics-creatives-schema-get)
- [Creative Daily Metrics](/api/analytics/creative-daily-metrics-api-v1-analytics-creatives-daily-get)
- [Creative Metrics](/api/analytics/creative-metrics-api-v1-analytics-creatives-get)

### Audit Log

- [Entity History](/api/audit-log/entity-history-api-v1-audit-logs-entity-type-entity-id-history-get)
- [List Audit Logs](/api/audit-log/list-audit-logs-api-v1-audit-logs-get)

### Comments

- [Add Reaction](/api/comments/add-reaction-api-v1-tasks-task-id-comments-comment-id-reactions-emoji-put)
- [Create Comment](/api/comments/create-comment-api-v1-tasks-task-id-comments-post)
- [Delete Comment](/api/comments/delete-comment-api-v1-tasks-task-id-comments-comment-id-delete)
- [List Comments](/api/comments/list-comments-api-v1-tasks-task-id-comments-get)
- [Remove Reaction](/api/comments/remove-reaction-api-v1-tasks-task-id-comments-comment-id-reactions-emoji-delete)
- [Update Comment](/api/comments/update-comment-api-v1-tasks-task-id-comments-comment-id-patch)

### Creative Tags

- [Delete Tag](/api/creative-tags/delete-tag-api-v1-tags-slug-delete)
- [List Tags](/api/creative-tags/list-tags-api-v1-tags-get)
- [Propose Tag](/api/creative-tags/propose-tag-api-v1-tags-post)
- [Set Tag Label](/api/creative-tags/set-tag-label-api-v1-tags-slug-label-patch)
- [Set Tag Status](/api/creative-tags/set-tag-status-api-v1-tags-slug-status-patch)

### Creatives

- [Add Creative Idea](/api/creatives/add-creative-idea-api-v1-creatives-creative-id-ideas-post)
- [Creative Notes Cloud](/api/creatives/creative-notes-cloud-api-v1-creatives-notes-cloud-get)
- [Creative Options](/api/creatives/creative-options-api-v1-creatives-options-get)
- [Creative Schemas](/api/creatives/creative-schemas-api-v1-creatives-schema-get)
- [Creative Variants](/api/creatives/creative-variants-api-v1-creatives-variants-get)
- [Creatives Gallery](/api/creatives/creatives-gallery-api-v1-creatives-gallery-get)
- [Delete Creative](/api/creatives/delete-creative-api-v1-creatives-creative-id-delete)
- [Get Creative](/api/creatives/get-creative-api-v1-creatives-creative-id-get)
- [Get Creative By Name](/api/creatives/get-creative-by-name-api-v1-creatives-by-name-name-get)
- [List Creatives](/api/creatives/list-creatives-api-v1-creatives-get)
- [Update Creative](/api/creatives/update-creative-api-v1-creatives-creative-id-patch)
- [Update Creative Idea](/api/creatives/update-creative-idea-api-v1-creatives-creative-id-ideas-idea-id-patch)

### Events

- [Live Events](/api/events/live-events-api-v1-events-get)

### Exports

- [Export Creatives](/api/exports/export-creatives-api-v1-exports-creatives-post)
- [Export Tasks](/api/exports/export-tasks-api-v1-exports-tasks-post)

### Frame Analysis

- [Create Frame Analysis](/api/frame-analysis/create-frame-analysis-api-v1-frame-analyses-post)
- [Creative Trend](/api/frame-analysis/creative-trend-api-v1-frame-analyses-creative-trend-get)
- [Delete Frame Analysis](/api/frame-analysis/delete-frame-analysis-api-v1-frame-analyses-run-id-delete)
- [Get Frame Analysis](/api/frame-analysis/get-frame-analysis-api-v1-frame-analyses-run-id-get)
- [List Frame Analyses](/api/frame-analysis/list-frame-analyses-api-v1-frame-analyses-get)
- [List Frame Analyses Expanded](/api/frame-analysis/list-frame-analyses-expanded-api-v1-frame-analyses-expanded-get)
- [Preview Frame Analysis](/api/frame-analysis/preview-frame-analysis-api-v1-frame-analyses-preview-post)

### Generated Assets

- [Get Asset](/api/generated-assets/get-asset-api-v1-assets-key-get)
- [List Asset Authors](/api/generated-assets/list-asset-authors-api-v1-assets-authors-get)
- [List Asset Tags](/api/generated-assets/list-asset-tags-api-v1-assets-tags-get)
- [List Assets](/api/generated-assets/list-assets-api-v1-assets-get)
- [Set Asset Tags](/api/generated-assets/set-asset-tags-api-v1-assets-key-tags-patch)

### Google Drive Files

- [Get Gdrive File](/api/google-drive-files/get-gdrive-file-api-v1-gdrive-files-get)
- [List Folder Files](/api/google-drive-files/list-folder-files-api-v1-gdrive-files-folders-folder-id-get)

### Health

- [Health](/api/health/health-health-get)

### Inbox

- [Get Preferences](/api/inbox/get-preferences-api-v1-inbox-preferences-get)
- [List Inbox](/api/inbox/list-inbox-api-v1-inbox-get)
- [Mark All Read](/api/inbox/mark-all-read-api-v1-inbox-read-all-post)
- [Mark Read](/api/inbox/mark-read-api-v1-inbox-read-post)
- [Mark Unread](/api/inbox/mark-unread-api-v1-inbox-unread-post)
- [Set Preferences](/api/inbox/set-preferences-api-v1-inbox-preferences-put)

### Integrations

- [Get Packs](/api/integrations/get-packs-api-v1-integrations-creative-tests-packs-get)
- [Lookup Creatives](/api/integrations/lookup-creatives-api-v1-integrations-creative-tests-creatives-lookup-post)
- [Mark Creatives Launched](/api/integrations/mark-creatives-launched-api-v1-integrations-creative-tests-creatives-launched-post)
- [Mark Packs Launched](/api/integrations/mark-packs-launched-api-v1-integrations-creative-tests-packs-launched-post)

### Node Graphs

- [Add Graph To Task](/api/node-graphs/add-graph-to-task-api-v1-graphs-graph-id-for-task-post)
- [Cancel Run](/api/node-graphs/cancel-run-api-v1-runs-run-id-cancel-post)
- [Create Graph](/api/node-graphs/create-graph-api-v1-graphs-post)
- [Create Graph From Template](/api/node-graphs/create-graph-from-template-api-v1-graphs-from-template-post)
- [Delete Graph](/api/node-graphs/delete-graph-api-v1-graphs-graph-id-delete)
- [Delete Run](/api/node-graphs/delete-run-api-v1-runs-run-id-delete)
- [Duplicate Graph](/api/node-graphs/duplicate-graph-api-v1-graphs-graph-id-duplicate-post)
- [Duplicate Run](/api/node-graphs/duplicate-run-api-v1-runs-run-id-duplicate-post)
- [Fork Run](/api/node-graphs/fork-run-api-v1-runs-run-id-fork-post)
- [Get Graph](/api/node-graphs/get-graph-api-v1-graphs-graph-id-get)
- [Get Run](/api/node-graphs/get-run-api-v1-runs-run-id-get)
- [Get Run Spend](/api/node-graphs/get-run-spend-api-v1-runs-run-id-spend-get)
- [Get Runs Spend](/api/node-graphs/get-runs-spend-api-v1-runs-spend-get)
- [Graph History](/api/node-graphs/graph-history-api-v1-graphs-graph-id-history-get)
- [Graph History At](/api/node-graphs/graph-history-at-api-v1-graphs-graph-id-history-at-get)
- [Graph Spend](/api/node-graphs/graph-spend-api-v1-graphs-spend-get)
- [List All Runs](/api/node-graphs/list-all-runs-api-v1-runs-get)
- [List Graphs](/api/node-graphs/list-graphs-api-v1-graphs-get)
- [List Node Specs](/api/node-graphs/list-node-specs-api-v1-nodes-get)
- [List Runs](/api/node-graphs/list-runs-api-v1-graphs-graph-id-runs-get)
- [Publish Template](/api/node-graphs/publish-template-api-v1-graphs-graph-id-template-post)
- [Restart Run](/api/node-graphs/restart-run-api-v1-runs-run-id-start-post)
- [Restore Graph History](/api/node-graphs/restore-graph-history-api-v1-graphs-graph-id-history-restore-post)
- [Restore Run](/api/node-graphs/restore-run-api-v1-runs-run-id-restore-post)
- [Restore Run History](/api/node-graphs/restore-run-history-api-v1-runs-run-id-history-restore-post)
- [Resume Run](/api/node-graphs/resume-run-api-v1-runs-run-id-resume-post)
- [Run As Of](/api/node-graphs/run-as-of-api-v1-runs-run-id-at-get)
- [Run History](/api/node-graphs/run-history-api-v1-runs-run-id-history-get)
- [Run History At](/api/node-graphs/run-history-at-api-v1-runs-run-id-history-at-get)
- [Start Run](/api/node-graphs/start-run-api-v1-graphs-graph-id-runs-post)
- [Unlink Graph Task](/api/node-graphs/unlink-graph-task-api-v1-graphs-graph-id-tasks-task-id-delete)
- [Update Graph](/api/node-graphs/update-graph-api-v1-graphs-graph-id-patch)
- [Update Run](/api/node-graphs/update-run-api-v1-runs-run-id-patch)

### Products

- [Create Product](/api/products/create-product-api-v1-products-post)
- [Delete Product](/api/products/delete-product-api-v1-products-product-id-delete)
- [Get Product](/api/products/get-product-api-v1-products-product-id-get)
- [List Products](/api/products/list-products-api-v1-products-get)
- [Update Product](/api/products/update-product-api-v1-products-product-id-patch)

### Task Templates

- [Create Task Template](/api/task-templates/create-task-template-api-v1-task-templates-post)
- [Delete Task Template](/api/task-templates/delete-task-template-api-v1-task-templates-template-id-delete)
- [List Task Templates](/api/task-templates/list-task-templates-api-v1-task-templates-get)
- [Update Task Template](/api/task-templates/update-task-template-api-v1-task-templates-template-id-patch)

### Tasks

- [Create Task](/api/tasks/create-task-api-v1-tasks-post)
- [Delete Task](/api/tasks/delete-task-api-v1-tasks-task-id-delete)
- [Deleted Tasks](/api/tasks/deleted-tasks-api-v1-tasks-deleted-get)
- [Get Task](/api/tasks/get-task-api-v1-tasks-task-id-get)
- [Restore Task](/api/tasks/restore-task-api-v1-tasks-task-id-restore-post)
- [Task History](/api/tasks/task-history-api-v1-tasks-task-id-history-get)
- [Task Options](/api/tasks/task-options-api-v1-tasks-options-get)
- [Task Rollups](/api/tasks/task-rollups-api-v1-tasks-rollups-get)
- [Task Schemas](/api/tasks/task-schemas-api-v1-tasks-schema-get)
- [Tasks Board](/api/tasks/tasks-board-api-v1-tasks-board-get)
- [Tasks Board Capacity](/api/tasks/tasks-board-capacity-api-v1-tasks-board-capacity-get)
- [Tasks Board Columns](/api/tasks/tasks-board-columns-api-v1-tasks-board-columns-get)
- [Transition Task Status](/api/tasks/transition-task-status-api-v1-tasks-task-id-status-patch)
- [Update Task](/api/tasks/update-task-api-v1-tasks-task-id-patch)

### Uploads

- [Upload File](/api/uploads/upload-file-api-v1-uploads-post)

### Users

- [Create User](/api/users/create-user-api-v1-users-post)
- [Delete User](/api/users/delete-user-api-v1-users-user-id-delete)
- [List Users](/api/users/list-users-api-v1-users-get)
- [Update User](/api/users/update-user-api-v1-users-user-id-patch)
- [User Options](/api/users/user-options-api-v1-users-options-get)

### Web Funnels

- [Web Funnel Metrics](/api/web-funnels/web-funnel-metrics-api-v1-web-funnels-get)
- [Web Funnel Schema](/api/web-funnels/web-funnel-schema-api-v1-web-funnels-schema-get)

### Webhooks

- [Clerk Webhook](/api/webhooks/clerk-webhook-webhooks-clerk-post)

## Backend

- [Локальний запуск](/backend/local-development): Як підняти Kumquat локально через make up-local — env-файли, профілі, override і Makefile.local.
- [Mongo-схема](/backend/db-schema): Колекції products → tasks → creatives, дзеркало users із Clerk і версіонування документів.
- [Воркфлоу задач](/backend/workflow): Статуси, переходи, автоматичне створення креативів, неймінг, сповіщення в Slack і Google Drive.
- [Автоматизація задач у канбані](/backend/tasks-kanban-automation): Контракт між Celery-воркером і канбаном — CAS у хендлері, відкат при збої enqueue, живі оновлення дошки.
- [Node-граф](/backend/node-graphs): Типізований DAG-executor і canvas-редактор — нода не знає про граф, executor рахує хвилями.
- [Коментарі до задач](/backend/comments-for-task): Створення коментарів, згадки користувачів, реакції, сповіщення в Slack і курсорний фід коментарів.
- [Інбокс: архітектура](/backend/inbox-notifications): Рядки сповіщень, dedupe, одна точка запису з преференсами, доставка через change stream і єдиний SSE на вкладку, sweep дедлайнів.
- [Аудит-лог](/backend/audit-log): Хто, що і коли змінив — одна append-only колекція audit__logs, декоратор @audited і відновлення стану з дельт.
- [Інтеграційний API](/backend/integration-api): Публічний контракт для сторонніх платформ — фід завершених паків, звіт про запуск (покреативний або цілим паком) і пошук креативів за іменем чи id кампанії разом із їхнім брифом.
- [Завантаження файлів — інфраструктура](/backend/uploads): S3-доступ, ліміти ingress і життєвий цикл об'єктів для аплоадів у task description.
- [Експорт таблиць у Google Sheets](/backend/exports): Спільні словники підписів, обхід фіду, Celery-задача і межі Drive.
- [Черга задач на MongoDB](/backend/mongo-queue): Claim через find_one_and_update, лізи з heartbeat, ретраї з backoff і рекламація прострочених задач.
- [Airflow DAG-и](/backend/airflow-dags): Шість DAG-ів у dags/, ланцюг import → scorecard → test-status на assets, параметри запуску, секрети й типові пастки KubernetesPodOperator.
- [Аналітика креативів — analytics API](/backend/creative-analytics): Три ендпоінти /analytics/creatives* над ClickHouse creative_performance — каталог вимірів і метрик, збірка SQL, кеш фільтрів і відомі розходження зі скоркардом.
- [Web funnels — API над solid_funnels_kumquat](/backend/web-funnels): Два ендпоінти /web-funnels над ClickHouse solid_funnels_kumquat — виміри, формули метрик, зв'язок із картками креативів і відомі межі.
- [Агент-аналітик: архітектура](/backend/analyst-agent-architecture): Чат-інтерфейс, який сам пише SQL до ClickHouse — ReAct-агент на LangChain зі стрімінгом через SSE.
- [Пагінація: keyset-курсор і дешевий count](/backend/range-based-cursor-pagination): Як фіди creatives, tasks, коментарів і історії гортаються двофазним keyset-курсором і чому total рахується лише на першій сторінці.

## Frontend

- [Архітектура frontend](/frontend/frontend-architecture): Довідник по структурі Kumquat Client — роути, модулі, сутності, сервіси.