Pachca

Pachca API

Pachca is a corporate messenger for teams. The REST API lets you automate communication workflows: send and manage messages, organize chats and channels, manage users and permissions, build interactive bots, handle file uploads, and react to real-time events via webhooks.

Base URL: https://api.pachca.com/api/shared/v1

Accessing Documentation

| Format | URL | Best for | |--------|-----|----------| | LLM-friendly summary | https://dev.pachca.com/llms.txt | Quick overview with links | | Full documentation | https://dev.pachca.com/llms-full.txt | Complete reference in one file | | OpenAPI 3.0 spec | https://dev.pachca.com/openapi.yaml | Programmatic parsing and code generation | | Arazzo workflows | https://dev.pachca.com/workflows.arazzo.yaml | Multi-step call sequences for chained operations | | CLI (per-endpoint, on demand) | npx -y @pachca/cli api --docs | One endpoint without loading the full file | | Markdown page | append .md to any page URL | Reading a single guide page as Markdown |

For detailed endpoint documentation, parameters, and response schemas, fetch /llms-full.txt — or, to avoid loading the whole file, pull just the endpoint you need with npx -y @pachca/cli api --describe (or --spec / --docs; list all endpoints: npx -y @pachca/cli api ls).

CLI (recommended)

# Zero-install
npx -y @pachca/cli  --token 

# For regular use
npm install -g @pachca/cli && pachca auth login

Authentication

All requests require a Bearer token. With CLI, use --token flag or PACHCA_TOKEN env var.

For direct API calls, add the Authorization header:

Authorization: Bearer 

Token types and their permissions:

• Admin token — full access: manage users, tags, delete messages. Get it in Settings → Automations → API.
• Owner token — admin access plus audit events and data export (Corporation plan only).
• Bot token — send messages with custom display name/avatar, receive webhook events, manage webhook settings. Created per-bot in Settings → Automations.

Tokens are long-lived and do not expire. They can be reset by the admin/owner in Settings.

Capabilities

OAuth

• GET /oauth/token/info — Get token info

Chats

• POST /chats — Create chat
• GET /chats — List chats
• POST /chats/exports — Request export
• GET /chats/exports/{id} — Download export
• GET /chats/{id} — Get chat
• PUT /chats/{id} — Update chat
• PUT /chats/{id}/archive — Archive chat
• PUT /chats/{id}/unarchive — Unarchive chat

Profile

• GET /profile — Get profile
• PUT /profile/avatar — Update profile avatar
• DELETE /profile/avatar — Delete profile avatar
• GET /profile/status — Get status
• PUT /profile/status — Update status
• DELETE /profile/status — Delete status

Users

• POST /users — Create user
• GET /users — List users
• GET /users/{id} — Get user
• PUT /users/{id} — Update user
• DELETE /users/{id} — Delete user
• PUT /users/{user_id}/avatar — Update user avatar
• DELETE /users/{user_id}/avatar — Delete user avatar
• GET /users/{user_id}/status — Get user status
• PUT /users/{user_id}/status — Update user status
• DELETE /users/{user_id}/status — Delete user status

Group tags

• POST /group_tags — Create tag
• GET /group_tags — List tags
• GET /group_tags/{id} — Get tag
• PUT /group_tags/{id} — Update tag
• DELETE /group_tags/{id} — Delete tag
• GET /group_tags/{id}/users — Get tag users

Members

• POST /chats/{id}/group_tags — Add tags
• DELETE /chats/{id}/group_tags/{tag_id} — Remove tag
• DELETE /chats/{id}/leave — Leave chat
• GET /chats/{id}/members — List members
• POST /chats/{id}/members — Add members
• DELETE /chats/{id}/members/{user_id} — Remove member
• PUT /chats/{id}/members/{user_id} — Update member role

Threads

• POST /messages/{id}/thread — Create thread
• GET /threads — List threads
• GET /threads/{id} — Get thread

Messages

• POST /messages — Create message
• GET /messages — List chat messages
• GET /messages/{id} — Get message
• PUT /messages/{id} — Update message
• DELETE /messages/{id} — Delete message
• POST /messages/{id}/link_previews — Unfurl
• POST /messages/{id}/pin — Pin message
• DELETE /messages/{id}/pin — Unpin message

Read members

• GET /messages/{id}/read_member_ids — List read members

Reactions

• POST /messages/{id}/reactions — Add reaction
• DELETE /messages/{id}/reactions — Remove reaction
• GET /messages/{id}/reactions — List reactions

Search

• GET /search/chats — Search chats
• GET /search/messages — Search messages
• GET /search/users — Search users

Tasks

• POST /tasks — Create task
• GET /tasks — List tasks
• GET /tasks/{id} — Get task
• PUT /tasks/{id} — Update task
• DELETE /tasks/{id} — Delete task

Views

• POST /views/open — Open view

Bots

• POST /bot/recreate_token — Self recreate bot token
• PUT /bot/webhook — Self update bot webhook
• POST /bots — Create bot
• GET /bots/{id} — Get bot
• PUT /bots/{id} — Update bot
• POST /bots/{id}/recreate_token — Recreate bot token
• GET /webhooks/events — Get webhook events
• DELETE /webhooks/events/{id} — Delete webhook event

Security

• GET /audit_events — Get audit events

Custom Properties

• GET /custom_properties — List properties

Files

• POST /direct_url — Upload file
• POST /uploads — Get upload params

Common Workflows

CLI Quick Start

npx -y @pachca/cli  --token 

Find chat by name and send message

1. List all chats, find by name field: pachca chats list --all

> GET /chats does not support name search — paginate through all

1. Send message to the chat: pachca messages create --entity-id= --content="Hello"

Find active chats in a date range

1. List chats with activity after a date: pachca chats list --last-message-at-after= --all

> Add --last-message-at-before for range. Date in ISO-8601 UTC

Set up a bot with outgoing webhook

1. Create bot in Pachca UI: Automations → Integrations → Webhook
2. Get access_token from bot API settings tab
3. Set Webhook URL to receive events

Show interactive form to user

1. Send message with button: pachca messages create --entity-id= --content="Fill the form" --buttons='[[{"text":"Open","data":"open_form"}]]'
2. On button click — receive webhook event with trigger_id
3. Open form immediately: pachca views open --type=modal --trigger-id= --title="Request" --blocks='[...]'

> trigger_id expires in 3 seconds — prepare form object in advance

1. On form submit — receive webhook, process data

Constraints

Rate Limits

• Message send/edit/delete: ~4 req/sec per chat (burst: 30/sec for 5s)
• Message read: ~10 req/sec
• Other endpoints: ~50 req/sec
• Webhooks: ~4 req/sec per webhook ID
• On 429 response, respect the Retry-After header.

Pagination

• Cursor-based (preferred): use limit (1–50) and cursor parameters. Response includes meta.paginate with next_page, prev_page, has_next, has_prev.
• Use has_next / has_prev to detect end of data. Use prev_page to poll for new records "above" the list.
• Search endpoints (/search/users, /search/chats, /search/messages) return only next_page and total.
• Offset-based (legacy): use per (1–50) and page parameters.

Permissions

• User management, tag management, and message deletion require an admin token.
• Audit events and data export require an owner token and Corporation pricing plan.
• Link preview (unfurling) requires a dedicated unfurling bot token with whitelisted domains.
• POST /direct_url is the only endpoint that does not require authentication.

Error Handling

• 400 — validation error
• 401 — missing or invalid token
• 403 — insufficient permissions
• 404 — resource not found
• 429 — rate limited (check Retry-After)

Error response body: { "errors": [{ "key": "field", "value": "description" }] }

Guides

Detailed documentation on specific topics is available at:

• Быстрый старт — Первый запрос к API Пачки за 5 минут: получение персонального токена, проверка авторизации и отправка сообщения через cURL, Postman или официальный CLI
• AI агенты, Обзор — Готовность Пачки к AI-агентам: агент как участник тредов и способы подключения — llms.txt, CLI как основной путь, Agent Skills, OpenAPI, Arazzo, Context7
• AI агенты, Взаимодействие с агентом — Как агент в Пачке получает события через вебхук, собирает контекст треда, выполняет действия и отвечает. Реакция-индикатор и таймер agent-thinking
• AI агенты, Markdown и документы — Агент присылает отчёты, ревью и сводки в Markdown — Пачка рендерит .md оформленной карточкой: таблицы, чеклисты, подсветка кода, diff, диаграммы Mermaid
• Треды — Треды в Пачке для разработчиков: сквозные треды как уникальная особенность, создание через POST /messages/{id}/thread, отправка комментариев, добавление участников, видимость родительского чата, нюансы API и поля Message.thread/rootchat_id
• Боты, Обзор — Боты в Пачке: что это, типы ботов, доступность в чатах и подмена имени и аватара отправителя в сообщениях
• Боты, Создание и настройка — Как создать бота в Пачке: выбор типа, копирование токена, настройка имени и аватара, настройка доступов и вкладок вебхуков и API
• Боты, Доступы к чатам и сообщениям — Как бот получает доступ к закрытым каналам и беседам, тредам и личным сообщениям в Пачке
• Боты, Готовые примеры реализации — Открытые примеры ботов для Пачки: Welcome Bot для приветствия новых сотрудников, Review Bot для интеграции с GitHub Pull Requests и Unfurl-бот для предпросмотра ссылок
• Входящие вебхуки — Входящие вебхуки в Пачке: отправка сообщений от имени бота одним HTTP POST без API, шаблонизатор для форматирования, интеграции с CI/CD и мониторингом
• Исходящие вебхуки, Обзор — Исходящие вебхуки в Пачке: что это, как настроить и какие настройки доступны на вкладке Исходящий Webhook в боте
• Исходящие вебхуки, Настройка и типы событий — Настройки исходящих вебхуков Пачки и список доступных типов событий: сообщения, реакции, нажатия кнопок, заполнение форм, изменение участников чатов и пространства, отправка ссылок
• Исходящие вебхуки, Безопасность и обработчик — Безопасность исходящих вебхуков Пачки: подпись HMAC-SHA256, проверка timestamp, IP-адрес отправителя, примеры обработчика на TypeScript и Python, идемпотентная обработка и доставка
• Исходящие вебхуки, Поллинг — Поллинг исходящих вебхуков Пачки через SDK: получение новых событий без публичного webhook URL, дедупликация доставок и пример воркера для локальной разработки
• Кнопки в сообщениях — Интерактивные кнопки в сообщениях ботов Пачки: ссылки и действия, обработка нажатий через исходящий вебхук, открытие форм и переходы на внешние ресурсы
• Формы, Обзор — Модальные формы ботов в Пачке: поля ввода, списки, даты и кнопки, жизненный цикл представления — от нажатия кнопки до валидации и закрытия модального окна
• Формы, Блоки представления — 10 типов блоков представлений в формах ботов Пачки: заголовок, текст, поля ввода, выбор из списка, дата, кнопки. До 100 блоков в одном представлении
• Формы, Обработка форм — Обработка форм в Пачке: открытие представлений по triggerid (3 секунды), приём результатов через исходящий вебхук, валидация полей и отображение ошибок
• Разворачивание ссылок — Unfurl в Пачке: превью ссылок внутренних сервисов прямо в чатах — бот ловит URL, подтягивает заголовок, описание, изображение и отправляет обратно в чат
• Экспорт сообщений — Экспорт сообщений из чатов Пачки: запрос архива за период до 45 дней, скачивание JSON-файлов, структура архива и ограничения по чатам. Тариф «Корпорация»
• DLP-система — DLP-система Пачки для защиты от утечек конфиденциальной информации: правила с условиями и действиями, приоритеты, контексты применения. Тариф «Корпорация»
• Журнал аудита событий — Журнал аудита событий Пачки для команд безопасности: типы событий, фильтрация по пользователю, периоду и типу, 90 дней хранения. Тариф «Корпорация»
• Форматирование текста — Какой markdown понимает Пачка в тексте сообщений, входящих вебхуках и блоках форм: жирный, курсив, зачёркнутый, ссылки, строчный код и блоки кода. Списки, цитаты и заголовки остаются обычным текстом.
• Сценарии — Пошаговые сценарии для типичных задач с API Пачки: какие методы вызывать и в каком порядке. Основа Agent Skills для AI-агентов и команды pachca guide в CLI
• CLI, Обзор — Официальный CLI для Pachca API: все методы API как команды терминала с автодополнением, типизированными флагами и интерактивными подсказками. Node.js 20+
• CLI, Установка — Установка @pachca/cli: глобально через npm или без установки через npx (для агентов и CI). Автодополнение, настройки по умолчанию, диагностика и обновление.
• CLI, Авторизация — Авторизация Pachca CLI: профили для нескольких токенов, приоритет источников токена, headless-режим для CI и агентов.
• CLI, Вывод — Форматы вывода Pachca CLI (table, json, yaml, csv), выбор колонок, плоский TSV-режим, пайпы и перенаправление, курсорная пагинация.
• CLI, Флаги и скрипты — Глобальные флаги Pachca CLI, сортировка, kebab-case, boolean-флаги, dry-run, деструктивные операции, exit codes, таксономия ошибок, переменные окружения, неинтерактивный режим.
• CLI, Сценарии — Готовые пошаговые сценарии Pachca CLI через pachca guide: поиск рецептов по задаче, последовательности команд с комментариями.
• CLI, Файлы — Загрузка файлов через Pachca CLI: pachca upload автоматически получает подпись и загружает на S3 одной командой.
• CLI, Прямые запросы — Команда pachca api: прямые HTTP-запросы к любому методу (поля -f/-F, инлайн JSON, stdin) и встроенный справочник по API (ls, --describe, --spec, --docs) прямо в терминале, без сайта документации.
• CLI, Команды — Справочник всех команд Pachca CLI: каждый метод API как команда, паттерн pachca [секция] [действие] [--флаги]. Параметры каждой команды — по клику.
• SDK, Обзор — Типизированные SDK для Pachca API на TypeScript, Python, Go, Kotlin, Swift и C#: автодополнение, retry и пагинация. Или свой клиент через OpenAPI-генератор
• SDK, TypeScript — Типизированный клиент для Pachca API на TypeScript: Node.js 18+ или любое окружение с fetch. Автодополнение, автопагинация и retry. npm-пакет @pachca/sdk
• [SDK, Python](https://dev.pachca.com/gui

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pachca
• Source: pachca/openapi
• License: MIT
• Homepage: https://dev.pachca.com

Install and usage instructions live in the source repository linked above.