Pachca API (pachca/openapi)

Pachca API

https://github.com/pachca/openapi
Admin
Pachca API is a comprehensive API documentation and SDK repository with auto-generated documentation...

Tokens:7,918
Snippets:44
Trust Score:7.5
Update:4 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# Pachca API

Pachca API is a Unified Developer Experience Platform for Pachca, a corporate messenger. The platform provides a single source of truth (TypeSpec + workflows) that generates artifacts for all channels: web docs, CLI, SDK, agent skills, and LLM context. The API enables building integrations, bots, and automation workflows for team communication, including sending messages, managing chats and channels, handling users, reactions, threads, tasks, and webhooks.

The platform offers multiple integration methods: a REST API with OpenAPI specification, official SDKs for TypeScript, Python, Go, Kotlin, and Swift, a full-featured CLI tool, and AI agent skills for seamless automation. All SDKs follow a unified pattern (`PachcaClient(token)` -> `client.service.method(request)`), and the API uses cursor-based pagination with automatic retry on rate limits.

## Authorization

All API requests require a Bearer token passed in the Authorization header. Tokens can be personal (user-based) or bot tokens.

```bash
# Request with Bearer token
curl "https://api.pachca.com/api/shared/v1/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Messages API

### Create Message

Send a message to a chat, channel, direct conversation, or thread. Use `entity_type: "user"` to send direct messages without creating a chat first.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "entity_type": "discussion",
      "entity_id": 334,
      "content": "Hello from API!",
      "files": [
        {"key": "attaches/files/93746/e354-...-5e6f/report.pdf", "name": "report.pdf"}
      ],
      "buttons": [
        [{"text": "Approve", "data": "approve_123"}],
        [{"text": "View Details", "url": "https://example.com/details"}]
      ]
    }
  }'

# Response: {"data": {"id": 194275, "entity_type": "discussion", "chat_id": 334, "content": "Hello from API!", ...}}
```

### List Messages

Retrieve messages from a chat with cursor-based pagination. Messages are returned in descending order by date.

```bash
curl "https://api.pachca.com/api/shared/v1/messages?chat_id=198&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": 194275, "content": "...", "user_id": 12, ...}], "meta": {"paginate": {"next_page": "eyJpZCI6MTB9"}}}

# Fetch next page
curl "https://api.pachca.com/api/shared/v1/messages?chat_id=198&cursor=eyJpZCI6MTB9" \
  -H "Authorization: Bearer $TOKEN"
```

### Update Message

Edit an existing message. Only the sender, admins, and editors can modify messages.

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/messages/194275" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "Updated message content",
      "buttons": []
    }
  }'
```

### Delete Message

Remove a message permanently. Available to the sender, admins, and editors.

```bash
curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/194275" \
  -H "Authorization: Bearer $TOKEN"
# Returns: 204 No Content
```

### Pin/Unpin Message

Pin or unpin a message in a chat.

```bash
# Pin message
curl -X POST "https://api.pachca.com/api/shared/v1/messages/194275/pin" \
  -H "Authorization: Bearer $TOKEN"

# Unpin message
curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/194275/pin" \
  -H "Authorization: Bearer $TOKEN"
```

## Chats API

### Create Chat

Create a new channel or group chat. For direct messages, use the Messages API with `entity_type: "user"`.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/chats" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat": {
      "name": "Project Alpha",
      "member_ids": [12, 186, 187],
      "channel": false,
      "public": true
    }
  }'

# Response: {"data": {"id": 334, "name": "Project Alpha", "channel": false, "public": true, ...}}
```

### List Chats

Get a list of chats with filtering and sorting options.

```bash
curl "https://api.pachca.com/api/shared/v1/chats?availability=is_member&limit=50&sort[last_message_at]=desc" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": 334, "name": "Project Alpha", "last_message_at": "2025-01-15T10:30:00Z", ...}], "meta": {...}}
```

### Get Chat Info

Retrieve detailed information about a specific chat.

```bash
curl "https://api.pachca.com/api/shared/v1/chats/334" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": {"id": 334, "name": "Project Alpha", "owner_id": 12, "member_count": 15, ...}}
```

### Archive/Unarchive Chat

Move a chat to archive or restore it.

```bash
# Archive
curl -X PUT "https://api.pachca.com/api/shared/v1/chats/334/archive" \
  -H "Authorization: Bearer $TOKEN"

# Unarchive
curl -X PUT "https://api.pachca.com/api/shared/v1/chats/334/unarchive" \
  -H "Authorization: Bearer $TOKEN"
```

## Users API

### List Users

Get the list of employees in your company with optional search filtering.

```bash
curl "https://api.pachca.com/api/shared/v1/users?query=Oleg&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": 12, "first_name": "Oleg", "last_name": "Petrov", "email": "oleg@company.com", "role": "admin", ...}], "meta": {...}}
```

### Create User

Add a new employee to the company with custom properties.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/users" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "email": "new.employee@company.com",
      "first_name": "Ivan",
      "last_name": "Sidorov",
      "department": "Engineering",
      "role": "user",
      "list_tags": ["developers", "backend"],
      "skip_email_notify": false
    }
  }'
```

### Update User

Modify user properties including custom fields.

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/users/12" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "department": "Product",
      "phone_number": "+7 999 123-45-67",
      "suspended": false
    }
  }'
```

## Members API

### Add Members to Chat

Add users or tags (groups) to a chat.

```bash
# Add users
curl -X POST "https://api.pachca.com/api/shared/v1/chats/334/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"member_ids": [186, 187], "silent": true}'

# Add tags (groups)
curl -X POST "https://api.pachca.com/api/shared/v1/chats/334/group_tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_tag_ids": [86, 18]}'
```

### List Chat Members

Get the list of participants in a chat with role filtering.

```bash
curl "https://api.pachca.com/api/shared/v1/chats/334/members?role=admin&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": 12, "first_name": "Oleg", ...}], "meta": {...}}
```

### Remove Member

Remove a user from a chat.

```bash
curl -X DELETE "https://api.pachca.com/api/shared/v1/chats/334/members/186" \
  -H "Authorization: Bearer $TOKEN"
```

## Reactions API

### Add Reaction

Add an emoji reaction to a message. Each user can add up to 20 unique reactions per message.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/messages/7231942/reactions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code": "👍"}'

# Response: {"user_id": 12, "code": "👍", "created_at": "2025-01-15T10:30:00Z"}
```

### List Reactions

Get all reactions on a message.

```bash
curl "https://api.pachca.com/api/shared/v1/messages/194275/reactions?limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"user_id": 12, "code": "👍", ...}, {"user_id": 186, "code": "🎉", ...}], "meta": {...}}
```

### Remove Reaction

Remove your own reaction from a message.

```bash
curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/7231942/reactions?code=%F0%9F%91%8D" \
  -H "Authorization: Bearer $TOKEN"
```

## Threads API

### Create Thread

Create a new thread (comment chain) under a message.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/messages/154332686/thread" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": {"id": 265142, "chat_id": 918264, "message_id": 154332686, ...}}
```

### Get Thread Info

Retrieve information about a thread.

```bash
curl "https://api.pachca.com/api/shared/v1/threads/265142" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": {"id": 265142, "chat_id": 918264, "updated_at": "2025-01-15T10:30:00Z", ...}}
```

## Tasks API

### Create Task (Reminder)

Create a new reminder/task with assignees and optional chat binding.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/tasks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "kind": "reminder",
      "content": "Review PR #123",
      "due_at": "2025-01-20T14:00:00Z",
      "performer_ids": [12, 186],
      "chat_id": 334
    }
  }'

# Response: {"data": {"id": 22283, "kind": "reminder", "content": "Review PR #123", ...}}
```

### List Tasks

Get all tasks/reminders.

```bash
curl "https://api.pachca.com/api/shared/v1/tasks?limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

## Search API

### Search Messages

Full-text search across messages with filters.

```bash
curl "https://api.pachca.com/api/shared/v1/search/messages?query=deploy&chat_ids=198,334&limit=10" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": 194275, "content": "Deploy completed successfully", ...}], "meta": {"total": 42, ...}}
```

### Search Users

Search employees by name, email, position, and other fields.

```bash
curl "https://api.pachca.com/api/shared/v1/search/users?query=engineer&company_roles=admin,user&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

### Search Chats

Full-text search for channels and group chats.

```bash
curl "https://api.pachca.com/api/shared/v1/search/chats?query=project&active=true&limit=10" \
  -H "Authorization: Bearer $TOKEN"
```

## File Upload API

### Upload File (3-Step Process)

Files are uploaded through a direct upload process to S3.

```bash
# Step 1: Get upload parameters
curl -X POST "https://api.pachca.com/api/shared/v1/uploads" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"direct_url": "https://storage.pachca.com/...", "key": "attaches/files/93746/e354-...-5e6f/${filename}", "policy": "...", ...}

# Step 2: Upload file to direct_url (no auth header!)
curl -X POST "https://storage.pachca.com/..." \
  -F "Content-Disposition=attachment" \
  -F "acl=private" \
  -F "policy=..." \
  -F "x-amz-credential=..." \
  -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
  -F "x-amz-date=..." \
  -F "x-amz-signature=..." \
  -F "key=attaches/files/93746/e354-...-5e6f/\${filename}" \
  -F "file=@report.pdf"

# Step 3: Attach to message (replace ${filename} with actual filename)
curl -X POST "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "entity_id": 334,
      "content": "Here is the report",
      "files": [{"key": "attaches/files/93746/e354-...-5e6f/report.pdf", "name": "report.pdf"}]
    }
  }'
```

## Webhooks API

### Incoming Webhook Events

Receive real-time events via outgoing webhooks. Configure webhook URL in bot settings.

```javascript
// Webhook payload structure for new message
{
  "event": "new",
  "type": "message",
  "webhook_timestamp": 1744618734,
  "chat_id": 918264,
  "content": "Hello from user",
  "user_id": 134412,
  "id": 56431,
  "created_at": "2025-04-14T08:18:54.000Z",
  "url": "https://app.pachca.com/chats/124511?message=56431"
}

// Verify webhook signature (Node.js)
const crypto = require('crypto');
const signature = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
if (signature !== request.headers['pachca-signature']) {
  throw new Error("Invalid signature");
}
```

### List Webhook Events (History Polling)

Get event history when real-time webhooks aren't available.

```bash
curl "https://api.pachca.com/api/shared/v1/webhooks/events?limit=50" \
  -H "Authorization: Bearer $BOT_TOKEN"

# Delete processed event
curl -X DELETE "https://api.pachca.com/api/shared/v1/webhooks/events/01KAJZ2XDSS2S3DSW9EXJZ0TBV" \
  -H "Authorization: Bearer $BOT_TOKEN"
```

## Forms API (Interactive Modals)

### Open Modal Form

Display an interactive form to a user. Requires a valid `trigger_id` from a button click webhook (valid for 3 seconds).

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/views/open" \
  -H "Authorization: Bearer $BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "abc123...",
    "view": {
      "title": "Request Time Off",
      "submit_label": "Submit",
      "callback_id": "timeoff_request",
      "private_metadata": "{\"user_id\":123}",
      "blocks": [
        {"type": "header", "text": "Time Off Request"},
        {"type": "input", "block_id": "date_start", "label": "Start Date", "required": true},
        {"type": "input", "block_id": "date_end", "label": "End Date", "required": true},
        {"type": "select", "block_id": "type", "label": "Type", "options": [
          {"text": "Vacation", "value": "vacation"},
          {"text": "Sick Leave", "value": "sick"}
        ]}
      ]
    }
  }'
```

## TypeScript SDK

The TypeScript SDK provides a typed client with automatic pagination and retry handling.

```typescript
import { PachcaClient } from "@pachca/sdk";

const pachca = new PachcaClient("YOUR_TOKEN");

// Send message
const message = await pachca.messages.createMessage({
  message: { entity_id: 334, content: "Hello from TypeScript!" }
});

// List users with automatic pagination
const allUsers = await pachca.users.listUsersAll();

// Add reaction (<=2 fields expanded as arguments)
await pachca.reactions.addReaction(message.id, { code: "👍" });

// Pin message
await pachca.messages.pinMessage(message.id);

// Create thread and reply
const thread = await pachca.threads.createThread(message.id);
await pachca.messages.createMessage({
  message: { entity_type: "thread", entity_id: thread.chat_id, content: "Thread reply" }
});

// Search
const results = await pachca.search.searchMessages({ query: "deploy", limit: 10 });
```

## Python SDK

The Python SDK provides async methods with automatic pagination and error handling.

```python
from pachca import PachcaClient, MessageCreateRequestMessage, ApiError, OAuthError

client = PachcaClient("YOUR_TOKEN")

# Create message
msg = await client.messages.create_message(
    MessageCreateRequestMessage(entity_id=334, content="Hello from Python!")
)

# Get message
fetched = await client.messages.get_message(msg.id)

# Add reaction
await client.reactions.add_reaction(msg.id, code="👀")

# Pin message
await client.messages.pin_message(msg.id)

# List with automatic pagination
all_chats = await client.chats.list_chats_all()

# Search users
results = await client.search.search_users(query="engineer", limit=10)

# Error handling
try:
    await client.messages.get_message(999999)
except OAuthError as e:
    print(f"Auth error: {e.message}")
except ApiError as e:
    print(f"API error: {e.errors}")
```

## CLI Usage

The CLI provides access to all API methods with multiple output formats.

```bash
# Install and authenticate
npm install -g @pachca/cli
pachca auth login

# Send message
pachca messages create --entity-id 334 --content "Hello from CLI!"

# List users with JSON output
pachca users list -o json

# Search with filters
pachca search list-messages --query "deploy" --chat-ids 198,334

# Create chat and add members
pachca chats create --name "New Project" --member-ids 12,186
pachca members add --id 334 --member-ids 187,188

# Pagination
pachca users list --all  # fetch all pages
pachca users list --limit 20 --cursor eyJpZCI6NTB9  # manual pagination

# Find commands by scenario
pachca guide "send file"
pachca guide "create chat and add members"

# Direct API requests
pachca api GET /profile -o yaml
pachca api POST /messages -F message[entity_id]=334 -f message[content]="Hello"
```

## Security API (Audit Events)

### Get Audit Events

Retrieve audit logs for compliance and security monitoring (requires Corporation plan).

```bash
curl "https://api.pachca.com/api/shared/v1/audit_events?start_time=2025-05-01T00:00:00Z&end_time=2025-05-02T00:00:00Z&event_key=user_login&limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": [{"id": "...", "event_key": "user_login", "actor_id": 12, "created_at": "2025-05-01T09:11:00Z", ...}], "meta": {...}}
```

## Group Tags API

### Create and Manage Tags

Tags (groups) allow organizing users and bulk-adding them to chats.

```bash
# Create tag
curl -X POST "https://api.pachca.com/api/shared/v1/group_tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_tag": {"name": "Backend Team"}}'

# List tags
curl "https://api.pachca.com/api/shared/v1/group_tags?names=Design,Product" \
  -H "Authorization: Bearer $TOKEN"

# Get tag members
curl "https://api.pachca.com/api/shared/v1/group_tags/9111/users?limit=50" \
  -H "Authorization: Bearer $TOKEN"

# Delete tag
curl -X DELETE "https://api.pachca.com/api/shared/v1/group_tags/9111" \
  -H "Authorization: Bearer $TOKEN"
```

## Profile API

### Get Current User Profile

Retrieve information about the authenticated user.

```bash
curl "https://api.pachca.com/api/shared/v1/profile" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": {"id": 12, "first_name": "Oleg", "email": "oleg@company.com", ...}}
```

### Manage User Status

Set or remove status with emoji and expiration.

```bash
# Set status
curl -X PUT "https://api.pachca.com/api/shared/v1/profile/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": {
      "emoji": "🏠",
      "title": "Working from home",
      "expires_at": "2025-01-15T18:00:00Z"
    }
  }'

# Get status
curl "https://api.pachca.com/api/shared/v1/profile/status" \
  -H "Authorization: Bearer $TOKEN"

# Delete status
curl -X DELETE "https://api.pachca.com/api/shared/v1/profile/status" \
  -H "Authorization: Bearer $TOKEN"
```

### Get Token Info

Verify token scopes and metadata.

```bash
curl "https://api.pachca.com/api/shared/v1/oauth/token/info" \
  -H "Authorization: Bearer $TOKEN"

# Response: {"data": {"id": 4827, "token": "cH5kR9mN...x7Qp", "scopes": ["messages:read", "chats:read"], "created_at": "2025-01-15T10:30:00Z", ...}}
```

## Summary

Pachca API provides comprehensive capabilities for building integrations with the corporate messenger. Common use cases include: automated notifications and alerts (CI/CD, monitoring, CRM events), chatbots for customer support and internal workflows, employee onboarding automation, message export and compliance, interactive forms for data collection, and link unfurling for custom previews. The API supports real-time webhooks for event-driven architectures and history polling for batch processing scenarios.

Integration patterns typically involve authenticating with personal or bot tokens, setting up webhooks for real-time events, using SDKs for type-safe development in TypeScript/Python/Go/Kotlin/Swift, or the CLI for scripting and automation. All endpoints support cursor-based pagination for large datasets, automatic retry with exponential backoff on rate limits (429), and consistent error handling with structured error responses. The platform generates AI agent skills that enable LLM-powered assistants to interact with Pachca through step-by-step CLI workflows.