===============
LIBRARY RULES
===============
From library maintainers:
- Base URL: https://api.pachca.com/api/shared/v1
- All requests require Bearer token in Authorization header
- Pagination is cursor-based: use 'limit' (1-50) and 'cursor' params, check meta.paginate.next_page
- Error response format: { errors: [{ key: 'field', value: 'description' }] }
- On 429 rate limit, respect the Retry-After header
- Full docs: https://dev.pachca.com/llms-full.txt | OpenAPI: https://dev.pachca.com/openapi.yaml | Skills: .agents/skills/

# Pachca API Documentation

Pachca is a Russian team collaboration platform that provides a comprehensive REST API for managing workspaces, users, chats, messages, tasks, and bots. The API enables developers to build integrations, automate workflows, and create chat bots that interact with Pachca's messaging and collaboration features. The platform offers real-time webhook notifications for events like new messages, reactions, and membership changes.

This documentation covers the Pachca API v1.0.0, which is served at `https://api.pachca.com/api/shared/v1`. The API uses Bearer token authentication and follows RESTful conventions with JSON request/response bodies. All endpoints support cursor-based pagination with a maximum of 50 items per request. SDKs are available for TypeScript, Python, Go, Kotlin, and Swift.

---

## Authentication

All API requests require Bearer token authentication. Obtain your access token from the Pachca workspace settings or bot configuration.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

---

## Users API

### List Users

Retrieves a paginated list of all employees in your workspace. Supports search filtering by name, email, phone number, and nickname.

```bash
# List all users with pagination
curl -X GET "https://api.pachca.com/api/shared/v1/users?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Search for users by name
curl -X GET "https://api.pachca.com/api/shared/v1/users?query=Олег&limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "meta": {
    "paginate": {
      "next_page": "eyJxZCO2MiwiZGlyIjomSNYjIn3"
    }
  },
  "data": [
    {
      "id": 12,
      "first_name": "Олег",
      "last_name": "Петров",
      "nickname": "olegpetrov",
      "email": "olegp@example.com",
      "department": "Продукт",
      "title": "CIO",
      "role": "admin",
      "suspended": false,
      "invite_status": "confirmed",
      "list_tags": ["Product", "Design"],
      "bot": false,
      "created_at": "2020-06-08T09:10:11.000Z",
      "last_activity_at": "2025-01-20T13:40:07.000Z",
      "time_zone": "Europe/Moscow"
    }
  ]
}
```

### Get User by ID

Retrieves detailed information about a specific employee by their unique identifier.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/users/12" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "data": {
    "id": 12,
    "first_name": "Олег",
    "last_name": "Петров",
    "nickname": "olegpetrov",
    "email": "olegp@example.com",
    "phone_number": "",
    "department": "Продукт",
    "title": "CIO",
    "role": "admin",
    "suspended": false,
    "invite_status": "confirmed",
    "list_tags": ["Product", "Design"],
    "custom_properties": [
      {
        "id": 1678,
        "name": "Город",
        "data_type": "string",
        "value": "Санкт-Петербург"
      }
    ],
    "user_status": null,
    "bot": false,
    "sso": false,
    "created_at": "2020-06-08T09:32:57.000Z",
    "last_activity_at": "2025-01-20T13:40:07.000Z",
    "time_zone": "Europe/Moscow",
    "image_url": null
  }
}
```

### Create User

Creates a new employee in your workspace. Requires admin access token. You can optionally skip email notification.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/users" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "first_name": "Олег",
      "last_name": "Петров",
      "email": "olegp@example.com",
      "department": "Продукт",
      "list_tags": ["Product", "Design"],
      "custom_properties": [
        {"id": 1678, "value": "Санкт-Петербург"}
      ]
    },
    "skip_email_notify": true
  }'

# Response: 201 Created with user object
```

### Update User

Updates an existing employee's information. Requires admin access token.

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/users/12" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "nickname": "olegpetrov",
      "role": "user",
      "list_tags": ["Product"]
    }
  }'
```

### Delete User

Removes an employee from your workspace. Requires admin access token.

```bash
curl -X DELETE "https://api.pachca.com/api/shared/v1/users/12" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"

# Response: 204 No Content
```

---

## Profile API

### Get Current Profile

Retrieves information about the currently authenticated user.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/profile" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "data": {
    "id": 12,
    "first_name": "Олег",
    "last_name": "Петров",
    "email": "olegp@example.com",
    "role": "admin",
    "bot": false
  }
}
```

### Get/Set User Status

Manage your current status with emoji and expiration time.

```bash
# Get current status
curl -X GET "https://api.pachca.com/api/shared/v1/profile/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Set new status
curl -X PUT "https://api.pachca.com/api/shared/v1/profile/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": {
      "emoji": "🎮",
      "title": "Очень занят",
      "expires_at": "2024-04-08T10:00:00.000Z"
    }
  }'

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

---

## Chats API

### List Chats

Retrieves a paginated list of chats available to the authenticated user. Supports filtering by availability, message time, and chat type.

```bash
# List all chats where user is a member
curl -X GET "https://api.pachca.com/api/shared/v1/chats?availability=is_member&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by last message time
curl -X GET "https://api.pachca.com/api/shared/v1/chats?last_message_at_after=2024-01-01T00:00:00.000Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "meta": {
    "paginate": {
      "next_page": "eyJpZCI6MTMsImRpciI6ImRlc2MifQ"
    }
  },
  "data": [
    {
      "id": 334,
      "name": "🤿 aqua",
      "created_at": "2021-08-28T15:56:53.000Z",
      "owner_id": 185,
      "member_ids": [185, 186, 187],
      "group_tag_ids": [],
      "channel": true,
      "personal": false,
      "public": false,
      "last_message_at": "2021-08-28T15:58:13.000Z",
      "meet_room_url": "https://meet.pachca.com/aqua-94bb21b5"
    }
  ]
}
```

### Create Chat

Creates a new chat (conversation or channel). The creator automatically becomes a member.

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

# Response: 201 Created
{
  "data": {
    "id": 334,
    "name": "🤿 aqua",
    "created_at": "2021-08-28T15:56:53.000Z",
    "owner_id": 185,
    "member_ids": [185, 186, 187],
    "channel": true,
    "personal": false,
    "public": false,
    "meet_room_url": "https://meet.pachca.com/aqua-94bb21b5"
  }
}
```

### Get/Update Chat

Retrieve or update chat information by ID.

```bash
# Get chat info
curl -X GET "https://api.pachca.com/api/shared/v1/chats/334" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update chat
curl -X PUT "https://api.pachca.com/api/shared/v1/chats/334" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat": {
      "name": "Бассейн",
      "public": true
    }
  }'
```

### Archive/Unarchive Chat

Move chats to archive or restore them.

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

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

---

## Chat Members API

### List Chat Members

Retrieves the list of members in a specific chat with optional role filtering.

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

# Response includes full user objects with pagination
```

### Add/Remove Members

Manage chat membership for users and tags.

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

# Remove member from chat
curl -X DELETE "https://api.pachca.com/api/shared/v1/chats/334/members/186" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Leave chat yourself
curl -X DELETE "https://api.pachca.com/api/shared/v1/chats/334/leave" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Update Member Role

Change a member's role within a chat (admin/user).

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/chats/334/members/186" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin"
  }'
```

### Add/Remove Tags

Manage group tags in chats.

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

# Remove tag from chat
curl -X DELETE "https://api.pachca.com/api/shared/v1/chats/334/group_tags/86" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

## Messages API

### List Chat Messages

Retrieves messages from a specific chat with pagination support.

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

# Response
{
  "data": [
    {
      "id": 1194277,
      "entity_type": "discussion",
      "entity_id": 198,
      "chat_id": 198,
      "content": "Это сообщение тоже попадёт в экспорт",
      "user_id": 12,
      "created_at": "2023-09-18T13:43:32.000Z",
      "url": "https://app.pachca.com/chats/198?message=1194277",
      "files": [],
      "buttons": [],
      "thread": {
        "id": 2633,
        "chat_id": 44997,
        "message_id": 1194277,
        "message_chat_id": 198,
        "updated_at": "2023-09-18T13:43:32.000Z"
      }
    }
  ],
  "meta": {
    "paginate": {
      "next_page": "eyJpZCI6MTE5NDI3NSwiZGlyIjoiZGVzYyJ9"
    }
  }
}
```

### Create Message

Sends a new message to a chat, personal conversation, or thread. Supports interactive buttons.

```bash
# Send message to a chat
curl -X POST "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "entity_type": "discussion",
      "entity_id": 198,
      "content": "Вчера мы продали 756 футболок (что на 10% больше, чем в прошлое воскресенье)",
      "buttons": [
        [
          {"text": "Подробнее", "url": "https://example.com/details"},
          {"text": "Отлично!", "data": "awesome"}
        ]
      ]
    }
  }'

# Send direct message to a user (creates chat automatically)
curl -X POST "https://api.pachca.com/api/shared/v1/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "entity_type": "user",
      "entity_id": 186,
      "content": "Привет! Как дела с проектом?"
    }
  }'

# Response: 201 Created
{
  "data": {
    "id": 194275,
    "entity_type": "discussion",
    "entity_id": 334,
    "chat_id": 334,
    "content": "Вчера мы продали 756 футболок",
    "user_id": 185,
    "created_at": "2021-08-28T15:57:23.000Z",
    "url": "https://app.pachca.com/chats/334?message=194275",
    "buttons": [[{"text": "Подробнее", "url": "https://example.com/details"}]]
  }
}
```

### Get/Update/Delete Message

Manage individual messages by ID.

```bash
# Get message
curl -X GET "https://api.pachca.com/api/shared/v1/messages/194275" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update message
curl -X PUT "https://api.pachca.com/api/shared/v1/messages/194275" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "Updated message content",
      "files": []
    }
  }'

# Delete message (requires admin/editor role)
curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/194275" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### Pin/Unpin Message

Pin important messages to a chat for easy access.

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

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

---

## Threads API

### Create Thread

Creates a new thread attached to a message for focused discussions.

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

# Response: 201 Created
{
  "data": {
    "id": 265142,
    "chat_id": 2637266155,
    "message_id": 154332686,
    "message_chat_id": 2637266154,
    "updated_at": "2023-02-01T19:20:47.204Z"
  }
}
```

### Get Thread Info

Retrieves information about a specific thread.

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

---

## Reactions API

### Add/Remove Reaction

Add emoji reactions to messages. Each user can add up to 20 unique reactions per message.

```bash
# Add reaction
curl -X POST "https://api.pachca.com/api/shared/v1/messages/194275/reactions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "👍",
    "name": ":+1:"
  }'

# Remove reaction
curl -X DELETE "https://api.pachca.com/api/shared/v1/messages/194275/reactions?code=👍" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

### List Reactions

Get all reactions on a message with user information.

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

# Response
{
  "data": [
    {
      "user_id": 76243,
      "created_at": "2023-09-11T14:59:35.000Z",
      "code": "👍",
      "name": ":+1:"
    },
    {
      "user_id": 27494,
      "created_at": "2023-09-11T15:01:47.000Z",
      "code": "🔥",
      "name": ":fire:"
    }
  ]
}
```

---

## Read Members API

### List Read Members

Get the list of user IDs who have read a specific message.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/messages/194275/read_member_ids?limit=300" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "data": [12, 13, 14, 15, 16],
  "meta": {
    "paginate": {
      "next_page": "eyJpZCI6MTYsImRpciI6ImFzYyJ9"
    }
  }
}
```

---

## Group Tags API

### List/Create Tags

Manage employee group tags for organization.

```bash
# List all tags
curl -X GET "https://api.pachca.com/api/shared/v1/group_tags?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by names
curl -X GET "https://api.pachca.com/api/shared/v1/group_tags?names[]=Design&names[]=iOS" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Create tag (requires admin)
curl -X POST "https://api.pachca.com/api/shared/v1/group_tags" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_tag": {
      "name": "Название тега"
    }
  }'

# Response
{
  "data": {
    "id": 9111,
    "name": "Design",
    "users_count": 6
  }
}
```

### Get/Update/Delete Tag

Manage individual tags by ID.

```bash
# Get tag info
curl -X GET "https://api.pachca.com/api/shared/v1/group_tags/9111" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update tag (requires admin)
curl -X PUT "https://api.pachca.com/api/shared/v1/group_tags/9111" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_tag": {
      "name": "Новое название тега"
    }
  }'

# Delete tag (requires admin)
curl -X DELETE "https://api.pachca.com/api/shared/v1/group_tags/9111" \
  -H "Authorization: Bearer YOUR_ADMIN_ACCESS_TOKEN"
```

### List Tag Users

Get all users assigned to a specific tag.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/group_tags/9111/users?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

## Tasks (Reminders) API

### List/Create Tasks

Manage reminders with different types: reminder, call, meeting, event, letter.

```bash
# List tasks
curl -X GET "https://api.pachca.com/api/shared/v1/tasks?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Create task
curl -X POST "https://api.pachca.com/api/shared/v1/tasks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "kind": "reminder",
      "content": "Забрать со склада 21 заказ",
      "due_at": "2020-06-05T12:00:00.000+03:00",
      "priority": 2,
      "custom_properties": [
        {"id": 78, "value": "Синий склад"}
      ]
    }
  }'

# Response
{
  "data": {
    "id": 22283,
    "kind": "reminder",
    "content": "Забрать со склада 21 заказ",
    "due_at": "2020-06-05T09:00:00.000Z",
    "priority": 2,
    "user_id": 12,
    "status": "undone",
    "created_at": "2020-06-04T10:37:57.000Z",
    "performer_ids": [12],
    "all_day": false
  }
}
```

### Get/Update/Delete Task

Manage individual tasks by ID.

```bash
# Get task
curl -X GET "https://api.pachca.com/api/shared/v1/tasks/22283" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Update task (mark as done)
curl -X PUT "https://api.pachca.com/api/shared/v1/tasks/22283" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "status": "done"
    }
  }'

# Delete task
curl -X DELETE "https://api.pachca.com/api/shared/v1/tasks/22283" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

## File Upload API

### Upload Files

Three-step process to upload files and attach them to messages.

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

# Response
{
  "Content-Disposition": "attachment",
  "acl": "private",
  "policy": "eyJloNBpcmF0aW9uIjoiMjAy...",
  "x-amz-credential": "286471_server/20211122/kz-6x/s3/aws4_request",
  "x-amz-algorithm": "AWS4-HMAC-SHA256",
  "x-amz-date": "20211122T065734Z",
  "x-amz-signature": "87e8f3ba4083c937c0e891d7a11tre932d8c33cg4bacf5380bf27624c1ok1475",
  "key": "attaches/files/93746/e354fd79-9jh6-f2hd-fj83-709dae24c763/$filename",
  "direct_url": "https://api.pachca.com/api/v3/direct_upload"
}

# Step 2: Upload file to direct_url with multipart/form-data
curl -X POST "https://api.pachca.com/api/v3/direct_upload" \
  -F "Content-Disposition=attachment" \
  -F "acl=private" \
  -F "policy=eyJloNBpcmF0aW9uIjoiMjAy..." \
  -F "x-amz-credential=286471_server/20211122/kz-6x/s3/aws4_request" \
  -F "x-amz-algorithm=AWS4-HMAC-SHA256" \
  -F "x-amz-date=20211122T065734Z" \
  -F "x-amz-signature=87e8f3ba4083c937c0e891d7a11tre932d8c33cg4bacf5380bf27624c1ok1475" \
  -F "key=attaches/files/93746/e354fd79-9jh6-f2hd-fj83-709dae24c763/$filename" \
  -F "file=@/path/to/your/file.png"

# Step 3: Use the file key in message (replace $filename with actual filename)
# key: "attaches/files/93746/e354fd79-9jh6-f2hd-fj83-709dae24c763/Логотип.png"
```

---

## Bots API

### Update Bot

Update bot configuration including webhook URL.

```bash
curl -X PUT "https://api.pachca.com/api/shared/v1/bots/1738816" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bot": {
      "webhook": {
        "outgoing_url": "https://www.website.com/tasks/new"
      }
    }
  }'
```

### Webhook Event History

Retrieve historical webhook events for bots that save event history.

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

# Response
{
  "data": [
    {
      "id": "01KAJZ5CMZFVK4FSZQOISFBZCS",
      "event_type": "message_new",
      "payload": {
        "event": "new",
        "type": "message",
        "webhook_timestamp": 1763637142,
        "chat_id": 43,
        "user_id": 13,
        "id": 4432345,
        "content": "Проверьте последнюю задачу",
        "url": "https://app.pachca.com/chats/43?message=4432345"
      },
      "created_at": "2025-11-20T11:12:22.000Z"
    }
  ]
}

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

---

## Link Previews (Unfurling) API

### Create Link Previews

Create rich link previews for URLs in bot messages. Requires unfurling bot access.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/messages/194275/link_previews" \
  -H "Authorization: Bearer YOUR_BOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "link_previews": [
      {
        "url": "https://example.com/article",
        "title": "Article Title",
        "description": "Article description text",
        "image_url": "https://example.com/image.png"
      }
    ]
  }'
```

---

## Views (Forms) API

### Open Modal View

Display interactive forms and modals to users. Requires a valid trigger_id from webhook events.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/views/open" \
  -H "Authorization: Bearer YOUR_BOT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "791a056b-006c-49dd-834b-c633fde52fe8",
    "type": "modal",
    "private_metadata": "{\"timeoff_id\":4378}",
    "callback_id": "timeoff_request_form",
    "view": {
      "title": "Уведомление об отпуске",
      "close_text": "Закрыть",
      "submit_text": "Отправить заявку",
      "blocks": [
        {
          "type": "plain_text",
          "text": "Заполните форму заявки на отпуск"
        },
        {
          "type": "date",
          "name": "date_start",
          "label": "Дата начала отпуска",
          "initial_date": "2025-07-01",
          "required": true
        },
        {
          "type": "date",
          "name": "date_end",
          "label": "Дата окончания отпуска",
          "initial_date": "2025-07-28",
          "required": true
        },
        {
          "type": "input",
          "name": "info",
          "label": "Описание",
          "placeholder": "Куда собираетесь",
          "multiline": true
        },
        {
          "type": "select",
          "name": "team",
          "label": "Выберите команду",
          "options": [
            {"text": "Web", "value": "web"},
            {"text": "iOS", "value": "ios", "selected": true},
            {"text": "Android", "value": "android"}
          ]
        }
      ]
    }
  }'
```

---

## Security & Audit API

### Get Audit Events

Retrieve audit logs for security monitoring. Requires Corporation plan and owner access token.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/audit_events?start_time=2025-05-01T00:00:00Z&end_time=2025-05-15T23:59:59Z&limit=50" \
  -H "Authorization: Bearer YOUR_OWNER_ACCESS_TOKEN"

# Response
{
  "data": [
    {
      "id": "a1b2c3d4-5e6f-7g8h-9i10-j11k12l13m14",
      "created_at": "2025-05-15T14:30:00.000Z",
      "event_key": "user_chat_join",
      "entity_id": "12345678",
      "entity_type": "Chat",
      "actor_id": "98765",
      "actor_type": "User",
      "details": {
        "inviter_id": "45678"
      },
      "ip_address": "192.168.1.100",
      "user_agent": "Pachca/3.60.0"
    }
  ],
  "meta": {
    "paginate": {
      "next_page": "eyJfa2QiOiJuIiwiY3JlYXRlZF9hdCI6..."
    }
  }
}
```

---

## Export API

### Request Message Export

Request an export of messages for specified chats and date range. Requires Corporation plan and owner access token.

```bash
curl -X POST "https://api.pachca.com/api/shared/v1/chats/exports" \
  -H "Authorization: Bearer YOUR_OWNER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_at": "2025-03-20",
    "end_at": "2025-03-20",
    "webhook_url": "https://webhook.site/your-webhook-id",
    "chat_ids": [1381521]
  }'

# Response: 204 No Content

# Download export archive when ready
curl -X GET "https://api.pachca.com/api/shared/v1/chats/exports/12345" \
  -H "Authorization: Bearer YOUR_OWNER_ACCESS_TOKEN" \
  -L -o export.zip
```

---

## Common API

### List Custom Properties

Get the list of custom fields defined for users or tasks in your workspace.

```bash
curl -X GET "https://api.pachca.com/api/shared/v1/custom_properties?entity_type=user" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "data": [
    {"id": 1487, "name": "Адрес", "data_type": "string"},
    {"id": 1489, "name": "Номер доступа", "data_type": "number"},
    {"id": 1572, "name": "Дата рождения", "data_type": "date"}
  ]
}
```

---

## Webhook Security

Verify incoming webhook signatures using HMAC-SHA256 to ensure authenticity.

```javascript
// Node.js example for webhook signature verification
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signature, signingSecret) {
  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

  if (signature !== expectedSignature) {
    throw new Error('Invalid signature');
  }

  // Also verify timestamp is within 1 minute
  const payload = JSON.parse(rawBody);
  const webhookTime = payload.webhook_timestamp * 1000;
  const now = Date.now();

  if (Math.abs(now - webhookTime) > 60000) {
    throw new Error('Webhook timestamp too old');
  }

  return payload;
}

// Express middleware usage
app.post('/webhook', (req, res) => {
  try {
    const payload = verifyWebhookSignature(
      req.rawBody,
      req.headers['pachca-signature'],
      process.env.WEBHOOK_SECRET
    );

    // Also validate IP address: 37.200.70.177

    // Process webhook...
    res.status(200).send('OK');
  } catch (error) {
    res.status(401).send('Unauthorized');
  }
});
```

---

## SDK Usage Examples

### TypeScript SDK

```typescript
import { createClient } from '@pachca/sdk';

const client = createClient({
  baseUrl: 'https://api.pachca.com/api/v1',
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
  },
});

// List users
const { data: users, error } = await client.GET('/users');

// Create message
const { data: message } = await client.POST('/messages', {
  body: {
    message: {
      entity_type: 'discussion',
      entity_id: 198,
      content: 'Hello from TypeScript SDK!',
    },
  },
});
```

### Python SDK

```python
from pachca import Client

client = Client(base_url="https://api.pachca.com/api/v1")
client.set_token("YOUR_TOKEN")

# List users
users = client.users.list()

# Create message
message = client.messages.create(
    entity_type="discussion",
    entity_id=198,
    content="Hello from Python SDK!"
)
```

### Go SDK

```go
package main

import (
    "context"
    "net/http"
    pachca "github.com/pachca/go-sdk"
)

func main() {
    client, _ := pachca.NewClientWithResponses(
        "https://api.pachca.com/api/v1",
        pachca.WithRequestEditorFn(func(ctx context.Context, req *http.Request) error {
            req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
            return nil
        }),
    )

    // List users
    users, _ := client.GetUsersWithResponse(context.Background())

    // Create message
    message, _ := client.PostMessagesWithResponse(context.Background(), pachca.PostMessagesJSONRequestBody{
        Message: pachca.MessageCreateRequest{
            EntityType: "discussion",
            EntityId:   198,
            Content:    "Hello from Go SDK!",
        },
    })
}
```

---

## Summary

The Pachca API provides comprehensive functionality for building integrations with the team collaboration platform. Common use cases include creating chat bots that respond to messages and button clicks, automating user management and onboarding workflows, building notification systems that send alerts to specific chats or users, integrating with external systems through webhooks and scheduled exports, and creating interactive forms for data collection.

Integration patterns typically involve setting up a bot with outgoing webhooks to receive real-time events, implementing signature verification for webhook security, using the event history endpoint for reliable event processing when real-time delivery fails, and leveraging the Views API for interactive user experiences. The API's cursor-based pagination makes it efficient to work with large datasets, and the available SDKs simplify integration in popular programming languages.