### Quick Start - Environment Setup

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Instructions for setting up the environment, including copying the example .env file and sourcing it.

```APIDOC
## Quick start

1. Create env:

```bash
cp .env.example .env
source .env
```

2. Fill `.env`.

Webhook example:

```bash
export B24_DOMAIN="your-portal.example"
export B24_AUTH_MODE="webhook"
export B24_WEBHOOK_USER_ID="1"
export B24_WEBHOOK_CODE="your_webhook_secret_without_user_id_prefix"
```

OAuth example:

```bash
export B24_DOMAIN="your-portal.example"
export B24_AUTH_MODE="oauth"
export B24_ACCESS_TOKEN="your_access_token"
export B24_REFRESH_TOKEN="your_refresh_token"
export B24_CLIENT_ID="your_client_id"
export B24_CLIENT_SECRET="your_client_secret"
```

3. Smoke tests:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}'
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.list --params '{"select":["ID","TITLE"],"start":0}'
```
```

--------------------------------

### Tasks Methods Examples

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Examples of common methods for managing tasks within the Bitrix24 system.

```APIDOC
## Tasks (examples)

- `tasks.task.add`
- `tasks.task.get`
- `tasks.task.list`
- `tasks.task.update`
- `tasks.task.complete`
```

--------------------------------

### Practical API Examples

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Examples of common Bitrix24 operations using the CLI client, including creating and updating leads, and performing batch calls.

```APIDOC
## Practical API examples

Create lead:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"Skill Demo Lead","NAME":"Agent"}}' \
  --confirm-write
```

Update lead:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.update \
  --params '{"id":1,"fields":{"COMMENTS":"Updated by agent"}}' \
  --confirm-write
```

Batch call:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py batch --params '{ 
  "halt":0,
  "cmd":{
    "lead_list":"crm.lead.list?select[0]=ID&select[1]=TITLE",
    "user":"user.current"
  }
}' --confirm-write
```

Offline events worker:

```bash
python3 skills/bitrix24-agent/scripts/offline_sync_worker.py --once
```
```

--------------------------------

### OAuth Call Example

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Example of making a POST request to a Bitrix24 OAuth endpoint using cURL.

```APIDOC
## Example: OAuth call

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Lead from AI agent"},"auth":"{access_token}"}' \
  "https://{portal}/rest/crm.lead.add"
```
```

--------------------------------

### CRM Methods Examples

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Examples of common methods for managing leads and deals within the CRM module.

```APIDOC
## CRM (examples)

- `crm.lead.add`
- `crm.lead.list`
- `crm.lead.update`
- `crm.deal.add`
- `crm.deal.list`
- `crm.deal.update`
```

--------------------------------

### Install Bitrix24 Skill for Moltbot

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Copy the Bitrix24 skill directory into the Moltbot skills directory. Ensure the ~/.moltbot/skills path exists.

```bash
mkdir -p ~/.moltbot/skills
cp -R skills/bitrix24-agent ~/.moltbot/skills/bitrix24-agent
```

--------------------------------

### Install Bitrix24 Skill for OpenClaw

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Copy the Bitrix24 skill directory into the OpenClaw skills directory. Ensure the ~/.openclaw/skills path exists.

```bash
mkdir -p ~/.openclaw/skills
cp -R skills/bitrix24-agent ~/.openclaw/skills/bitrix24-agent
```

--------------------------------

### Start Workflow

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-automation.md

Initiates a new business process workflow. Requires 'write' permissions.

```APIDOC
## bizproc.workflow.start

### Description
Starts a new business process workflow.

### Method
POST

### Endpoint
/api/bizproc.workflow.start

### Parameters
#### Query Parameters
- **auth** (string) - Required - Authentication token.

#### Request Body
- **document_type** (string) - Required - The type of the document to start the workflow for.
- **document_id** (string) - Required - The ID of the document.
- **template_id** (string) - Required - The ID of the workflow template to use.
- **parameters** (object) - Optional - An object containing parameters for the workflow.

### Request Example
```json
{
  "auth": "your_auth_token",
  "document_type": "list_section",
  "document_id": "123",
  "template_id": "456",
  "parameters": {
    "field1": "value1"
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - An object containing the ID of the started workflow.
  - **workflow_id** (string) - The ID of the newly started workflow.

#### Response Example
```json
{
  "result": {
    "workflow_id": "789"
  }
}
```
```

--------------------------------

### Webhook Call Example

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Example of making a POST request to a Bitrix24 webhook endpoint using cURL.

```APIDOC
## Example: webhook call

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Lead from AI agent"}}' \
  "https://{portal}/rest/{user_id}/{webhook}/crm.lead.add"
```
```

--------------------------------

### OAuth Call Example (REST v2)

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Illustrates making a POST request to a Bitrix24 OAuth endpoint using cURL. This method requires an access token for authentication. Replace {portal} and {access_token} with your specific values.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Lead from AI agent"},"auth":"{access_token}"}' \
  "https://{portal}/rest/crm.lead.add"
```

--------------------------------

### Create a New Lead in Bitrix24

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Example of creating a new lead in Bitrix24 using the crm.lead.add method with specified title and name. Requires --confirm-write to execute.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"Skill Demo Lead","NAME":"Agent"}}' \
  --confirm-write
```

--------------------------------

### Webhook Call Example (REST v2)

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Demonstrates how to make a POST request to a Bitrix24 webhook endpoint using cURL. Ensure to replace placeholders like {portal}, {user_id}, and {webhook} with actual values.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"fields":{"TITLE":"Lead from AI agent"}}' \
  "https://{portal}/rest/{user_id}/{webhook}/crm.lead.add"
```

--------------------------------

### Combine Multiple Capability Packs for a Call

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Specify multiple capability packs for a single API call using a comma-separated list with the `--packs` argument. This example combines `core` and `comms` packs.

```bash
# Enable multiple packs for a single call
python3 skills/bitrix24-agent/scripts/bitrix24_client.py im.message.add \
  --params '{"DIALOG_ID":"chat123","MESSAGE":"Hello from agent"}' \
  --packs core,comms \
  --confirm-write
```

--------------------------------

### Search for Catalog and Chains References

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/SKILL.md

Use this command to quickly find relevant information about method catalogs and implementation chains within the references directory.

```bash
rg -n "^# Catalog|^# Chains" references/catalog-*.md references/chains-*.md
```

--------------------------------

### Run Bitrix24 Method with Parameters

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Use this command to run any Bitrix24 method. It requires the method name, parameters in JSON format, and optionally allows unlisted methods and confirms write operations.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> \
  --params '<json>' \
  --allow-unlisted \
  --confirm-write
```

--------------------------------

### Use Diagnostics Pack for Method Information

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Enable the diagnostics pack along with the core pack to retrieve detailed information about a specific Bitrix24 method.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py method.get \
  --params '{"name":"crm.lead.add"}' \
  --packs core,diagnostics
```

--------------------------------

### Entity Management

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-platform.md

Manage entities and their items, including getting, adding, and updating.

```APIDOC
## entity.get

### Description
Retrieves information about a specific entity.

### Method
GET

### Endpoint
/api/v1/entity/get

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier of the entity.

### Response
#### Success Response (200)
- **name** (string) - The name of the entity.
- **fields** (array) - List of fields associated with the entity.

### Response Example
{
  "name": "Contacts",
  "fields": [
    {"name": "Name", "type": "string"},
    {"name": "Email", "type": "email"}
  ]
}
```

```APIDOC
## entity.add

### Description
Adds a new entity.

### Method
POST

### Endpoint
/api/v1/entity/add

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new entity.
- **fields** (array) - Required - The fields for the new entity.

### Request Example
{
  "name": "Leads",
  "fields": [
    {"name": "Company", "type": "string"},
    {"name": "Status", "type": "dropdown"}
  ]
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly added entity.

### Response Example
{
  "id": "entity_id_3"
}
```

```APIDOC
## entity.update

### Description
Updates an existing entity.

### Method
PUT

### Endpoint
/api/v1/entity/update

### Parameters
#### Request Body
- **id** (string) - Required - The unique identifier of the entity to update.
- **name** (string) - Optional - The new name for the entity.
- **fields** (array) - Optional - The updated fields for the entity.

### Request Example
{
  "id": "entity_id_3",
  "name": "Updated Leads"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the update was successful.

### Response Example
{
  "success": true
}
```

```APIDOC
## entity.item.get

### Description
Retrieves a specific item from an entity.

### Method
GET

### Endpoint
/api/v1/entity/item/get

### Parameters
#### Query Parameters
- **entityId** (string) - Required - The ID of the entity.
- **itemId** (string) - Required - The ID of the item.

### Response
#### Success Response (200)
- **data** (object) - The data of the item.

### Response Example
{
  "data": {
    "Name": "Example Company",
    "Status": "New"
  }
}
```

```APIDOC
## entity.item.add

### Description
Adds a new item to an entity.

### Method
POST

### Endpoint
/api/v1/entity/item/add

### Parameters
#### Request Body
- **entityId** (string) - Required - The ID of the entity.
- **data** (object) - Required - The data for the new item.

### Request Example
{
  "entityId": "entity_id_3",
  "data": {
    "Company": "New Client",
    "Status": "Prospect"
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly added item.

### Response Example
{
  "id": "item_id_4"
}
```

--------------------------------

### Run Unit Tests (No Portal Required)

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Executes unit tests for the Bitrix24 client and offline sync worker without requiring a Bitrix24 portal connection.

```bash
python3 -m unittest tests.test_bitrix24_client -v
```

```bash
python3 -m unittest tests.test_offline_sync_worker -v
```

--------------------------------

### List Available Capability Packs via CLI

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Retrieve a list of available capability packs for the client using the `--list-packs` flag.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current \
  --params '{}' --list-packs
```

--------------------------------

### Instantiate Bitrix24Client in Python

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Demonstrates creating a `Bitrix24Client` instance for webhook and OAuth modes. Supports custom timeouts, retry attempts, and rate limiting.

```python
import pathlib
from bitrix24_client import (
    Bitrix24Client, TenantConfig, TokenStore,
    BitrixAPIError, FileRateLimiter,
    refresh_via_oauth_server,
)

# --- Webhook mode ---
tenant = TenantConfig(
    domain="my-portal.bitrix24.com",
    auth_mode="webhook",
    webhook_user_id="1",
    webhook_code="abc123secret",
)
client = Bitrix24Client(
    tenant,
    timeout=30,
    max_attempts=5,
    rate_limiter=FileRateLimiter(
        pathlib.Path(".runtime/rate_limiter.json"),
        rate_per_sec=2.0,
        burst=10.0,
    ),
)

# --- OAuth mode with auto-refresh ---
oauth_tenant = TenantConfig(domain="my-portal.bitrix24.com", auth_mode="oauth")
token_store = TokenStore(access_token="<access>", refresh_token="<refresh>")
oauth_client = Bitrix24Client(
    oauth_tenant,
    token_store=token_store,
    refresh_callback=refresh_via_oauth_server,  # auto-refreshes on expired_token
)

try:
    result = client.call("user.current", params={})
    print(result["result"])
    # {"ID": "1", "NAME": "John", "LAST_NAME": "Doe", ...}
except BitrixAPIError as exc:
    print(f"code={exc.code} retryable={exc.retryable} fatal={exc.fatal}: {exc}")
```

--------------------------------

### Sprint Management

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-boards.md

Methods for managing sprints within a Bitrix24 project, including listing, adding, starting, and completing sprints.

```APIDOC
## tasks.api.scrum.sprint.list

### Description
Retrieves a list of sprints.

### Method
GET

### Endpoint
/api/tasks.api.scrum.sprint.list

### Response
#### Success Response (200)
- sprints (array) - List of sprint objects.
```

```APIDOC
## tasks.api.scrum.sprint.add

### Description
Adds a new sprint.

### Method
POST

### Endpoint
/api/tasks.api.scrum.sprint.add

### Request Body
- title (string) - Required - The title of the sprint.
- startDate (string) - Optional - The start date of the sprint (YYYY-MM-DD).
- endDate (string) - Optional - The end date of the sprint (YYYY-MM-DD).

### Response
#### Success Response (200)
- sprintId (integer) - The ID of the newly created sprint.
```

```APIDOC
## tasks.api.scrum.sprint.start

### Description
Starts an existing sprint.

### Method
POST

### Endpoint
/api/tasks.api.scrum.sprint.start

### Request Body
- sprintId (integer) - Required - The ID of the sprint to start.

### Response
#### Success Response (200)
- success (boolean) - Indicates if the sprint was successfully started.
```

```APIDOC
## tasks.api.scrum.sprint.complete

### Description
Completes an active sprint.

### Method
POST

### Endpoint
/api/tasks.api.scrum.sprint.complete

### Request Body
- sprintId (integer) - Required - The ID of the sprint to complete.

### Response
#### Success Response (200)
- success (boolean) - Indicates if the sprint was successfully completed.
```

--------------------------------

### Run Integration Smoke Tests

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Execute live smoke tests against a real Bitrix24 portal by setting environment variables for credentials and running the unittest module.

```bash
# Set up live portal credentials
export B24_DOMAIN="your-test-portal.bitrix24.com"
export B24_AUTH_MODE="webhook"
export B24_WEBHOOK_USER_ID="1"
export B24_WEBHOOK_CODE="your_code"

# Run read-only smoke tests
export B24_RUN_INTEGRATION="1"
python3 -m unittest tests.test_integration_smoke -v
# test_crm_lead_list ... ok
# test_method_get ... ok
# test_user_current ... ok

```

--------------------------------

### Sprint Kickoff Operations

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/chains-boards.md

Operations related to initiating a new sprint, including adding a sprint and starting it, along with retrieving Kanban stages.

```APIDOC
## Sprint Kickoff

### Description
Operations to start a new sprint.

### Methods
- `tasks.api.scrum.sprint.add`
- `tasks.api.scrum.sprint.start`
- `tasks.api.scrum.kanban.getStages`
```

--------------------------------

### List Available Packs for Bitrix24 CLI

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Use the --list-packs flag to see all available packs that can be enabled for the Bitrix24 CLI client.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}' --list-packs
```

--------------------------------

### Bitrix24 Event Callback Endpoint (Node.js/Express)

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

Set up an Express.js endpoint to receive and process events from Bitrix24. This example includes basic authentication and enqueues events for asynchronous processing.

```javascript
app.post("/bitrix/events", express.urlencoded({ extended: true }), (req, res) => {
  const event = req.body?.event;
  const auth = req.body?.auth || {};
  const appToken = auth.application_token;
  const memberId = auth.member_id;

  const tenant = tenantStore.findByMemberId(memberId);
  if (!tenant) {
    return res.status(404).json({ ok: false, reason: "unknown_tenant" });
  }

  if (!appToken || appToken !== tenant.applicationToken) {
    return res.status(403).json({ ok: false, reason: "invalid_application_token" });
  }

  // enqueue event for async processing
  queue.push({ tenantId: tenant.id, event, payload: req.body });
  return res.json({ ok: true });
});
```

--------------------------------

### Set Up Environment Variables for OAuth Authentication

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Configure environment variables for Bitrix24 OAuth authentication. This includes setting the domain, auth mode, access token, refresh token, client ID, and client secret.

```bash
export B24_DOMAIN="your-portal.example"
export B24_AUTH_MODE="oauth"
export B24_ACCESS_TOKEN="your_access_token"
export B24_REFRESH_TOKEN="your_refresh_token"
export B24_CLIENT_ID="your_client_id"
export B24_CLIENT_SECRET="your_client_secret"
```

--------------------------------

### Update an Existing Lead in Bitrix24

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Example of updating an existing lead in Bitrix24 using the crm.lead.update method. Specify the lead ID and the fields to update. Requires --confirm-write.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.update \
  --params '{"id":1,"fields":{"COMMENTS":"Updated by agent"}}' \
  --confirm-write
```

--------------------------------

### Load Tenant Configuration from Environment Variables

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Load tenant configuration and token store from environment variables for webhook or OAuth modes. Raises ValueError if required variables are missing.

```python
import os
from unittest import mock
from bitrix24_client import load_tenant_config_from_env, Bitrix24Client

# Webhook mode
with mock.patch.dict(os.environ, {
    "B24_DOMAIN": "portal.bitrix24.com",
    "B24_AUTH_MODE": "webhook",
    "B24_WEBHOOK_USER_ID": "1",
    "B24_WEBHOOK_CODE": "mysecret",
}):
    tenant, token_store = load_tenant_config_from_env()
    client = Bitrix24Client(tenant, token_store=token_store)
    print(tenant.auth_mode)       # "webhook"
    print(token_store.get_tokens()) # (None, None)

# OAuth mode
with mock.patch.dict(os.environ, {
    "B24_DOMAIN": "portal.bitrix24.com",
    "B24_AUTH_MODE": "oauth",
    "B24_ACCESS_TOKEN": "tok_abc",
    "B24_REFRESH_TOKEN": "ref_xyz",
}):
    tenant, token_store = load_tenant_config_from_env()
    print(token_store.get_tokens()) # ("tok_abc", "ref_xyz")

```

--------------------------------

### Bitrix24 Client: General Command Template

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/SKILL.md

A general template for executing Bitrix24 API methods. It includes parameters for method, JSON payload, and pack selection.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> \
  --params '<json>' \
  --packs core
```

--------------------------------

### Add Lead via CLI with Confirmation

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Use the CLI to add a lead. Write operations require the `--confirm-write` flag for safety.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"CLI Lead","NAME":"Agent"}}' \
  --packs core \
  --confirm-write
```

--------------------------------

### methods

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-diagnostics.md

Retrieves a list of all available methods.

```APIDOC
## GET methods

### Description
Retrieves a list of all available methods in the Bitrix24 API.

### Method
GET

### Endpoint
/rest/methods

### Response
#### Success Response (200)
- **result** (array) - An array of method names.

### Response Example
{
  "result": [
    "method.get",
    "methods",
    "events",
    "scope",
    "feature.get",
    "server.time"
  ]
}
```

--------------------------------

### Set Up Environment Variables for Webhook Authentication

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Configure environment variables for Bitrix24 webhook authentication. This includes setting the domain, auth mode, user ID, and webhook code.

```bash
export B24_DOMAIN="your-portal.example"
export B24_AUTH_MODE="webhook"
export B24_WEBHOOK_USER_ID="1"
export B24_WEBHOOK_CODE="your_webhook_secret_without_user_id_prefix"
```

--------------------------------

### Configure Bitrix24 Environment Variables

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Set environment variables for Bitrix24 connection in webhook or OAuth mode. Includes options for safety and quality controls.

```bash
# Webhook mode (single-portal, no OAuth dance)
export B24_DOMAIN="your-portal.bitrix24.com"
export B24_AUTH_MODE="webhook"
export B24_WEBHOOK_USER_ID="1"
export B24_WEBHOOK_CODE="abc123secretcode"

# OAuth mode (multi-portal / marketplace apps)
# export B24_AUTH_MODE="oauth"
# export B24_ACCESS_TOKEN="<access_token>"
# export B24_REFRESH_TOKEN="<refresh_token>"
# export B24_CLIENT_ID="<client_id>"
# export B24_CLIENT_SECRET="<client_secret>"

# Safety / quality controls
export B24_PACKS="core"                               # active capability packs
export B24_AUDIT_FILE=".runtime/b24_audit.jsonl"      # JSONL audit trail
export B24_REQUIRE_PLAN="1"                           # force plan->execute for writes
export B24_RATE_LIMITER="file"                        # cross-process token-bucket limiter
export B24_RATE_LIMITER_RATE="2.0"                    # requests/second sustained
export B24_RATE_LIMITER_BURST="10.0"                  # burst allowance
export B24_IDEMPOTENCY_FILE=".runtime/b24_idem.json"  # replay-protection store
```

--------------------------------

### CLI - Direct Method Calls

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Interact with the Bitrix24 API directly from the command line using the provided Python script. Supports read, write, destructive, and batch operations.

```APIDOC
## CLI Commands

### Description
Execute Bitrix24 API methods directly via the command-line interface. This tool wraps the Python client's functionality, allowing for direct method invocation, parameter passing, and confirmation for sensitive operations.

### Usage
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> --params '<json_string>' [--confirm-write] [--confirm-destructive] [--packs <pack_name>] [--rest-v3]
```

### Examples
#### Read Operation
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}'
```

#### Write Operation (requires confirmation)
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"CLI Lead","NAME":"Agent"}}' \
  --packs core \
  --confirm-write
```

#### Destructive Operation (requires confirmation)
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.delete \
  --params '{"id":42}' \
  --confirm-destructive
```

#### Batch Call
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py batch \
  --params '{"halt":0,"cmd":{"leads":"crm.lead.list?select[0]=ID","me":"user.current"}}' \
  --packs core
```

#### Use REST v3 Endpoint (OAuth Mode)
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.list \
  --params '{"select":["ID","TITLE"]}' \
  --rest-v3
```

#### List Available Packs
```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current \
  --params '{}' --list-packs
```
```

--------------------------------

### Project Directory Structure

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Overview of the file and directory layout for the Bitrix24 agent skill pack.

```text
skills/bitrix24-agent/
  SKILL.md
  references/
    bitrix24.md
    packs.md
    catalog-*.md
    chains-*.md
  scripts/
    bitrix24_client.py
    offline_sync_worker.py
  agents/openai.yaml
```

--------------------------------

### List Leads via Python Client (REST v3)

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Fetch a list of leads using the `client.call` method with `rest_v3=True`. This format is recommended for OAuth-only integrations.

```python
response = client.call("crm.lead.list", params={"select": ["ID", "TITLE"]}, rest_v3=True)
```

--------------------------------

### Running Unlisted Methods

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

How to run a Bitrix24 method that is not explicitly listed in the skill's catalog, useful for testing and adding new functionality.

```APIDOC
## If the skill does not cover a Bitrix24 function

1. Verify method in official docs (`bitrix24/b24restdocs`) and required scope.
2. Run it once in controlled mode:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py <method> \
  --params '<json>' \
  --allow-unlisted \
  --confirm-write
```

3. If it is stable and useful, add it to the right pack:
- update `skills/bitrix24-agent/references/catalog-<pack>.md`
- add/update a recipe in `skills/bitrix24-agent/references/chains-<pack>.md`
- extend allowlist patterns in `skills/bitrix24-agent/scripts/bitrix24_client.py` (`PACK_METHOD_ALLOWLIST`)
4. Re-run smoke checks and commit.
```

--------------------------------

### Search for Offline Event and Token References

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/SKILL.md

Use this command to find information related to offline event handling and application token validation within the bitrix24.md reference file.

```bash
rg -n "offline|event\.bind|event\.offline|application_token" references/bitrix24.md
```

--------------------------------

### Bitrix24 Capability Packs Overview

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Lists the different capability packs available for Bitrix24 integrations, detailing their focus areas.

```text
| Pack | Focus |
|---|---|
| `core` | CRM + tasks.task + user + events + batch |
| `comms` | Chats, chat-bots, messaging, telephony |
| `automation` | Bizproc/robots/templates |
| `collab` | Workgroups/socialnetwork/feed-style collaboration |
| `content` | Disk/files/document flows |
| `boards` | Scrum/board methods |
| `commerce` | Sale/catalog: orders, payments, deliveries, products |
| `services` | Booking/calendar/timeman operations |
| `platform` | AI, entity storage, biconnector |
| `sites` | Landing/site/page management |
| `compliance` | User consent and sign-b2e document tails |
| `diagnostics` | Method/scope/feature/events compatibility checks |
```

--------------------------------

### PlanStore for Persisted Execution Plans

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Create, inspect, and consume single-use execution plans with a Time-To-Live (TTL). Plans expire after `ttl_sec` and can only be consumed once, preventing accidental re-execution.

```python
import pathlib
from bitrix24_client import PlanStore

store = PlanStore(pathlib.Path(".runtime/plans.json"), ttl_sec=1800)

plan = store.create(
    tenant="my-portal.bitrix24.com",
    method="crm.lead.add",
    params={"fields": {"TITLE": "Staged Lead"}},
    risk="write",
    allowlisted=True,
    packs=["core"],
)
print(plan["plan_id"])    # "a1b2c3d4e5f6g7h8i9j0"
print(plan["expires_at"]) # unix timestamp

# Consume exactly once (raises ValueError if expired or already executed)
consumed = store.consume(plan["plan_id"], tenant="my-portal.bitrix24.com")
print(consumed["method"])  # "crm.lead.add"

# Second consume raises:
# ValueError: plan 'a1b2c3d4e5f6g7h8i9j0' already executed
```

--------------------------------

### method.get

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-diagnostics.md

Retrieves information about a specific method.

```APIDOC
## GET method.get

### Description
Retrieves detailed information about a specific Bitrix24 API method.

### Method
GET

### Endpoint
/rest/method.get

### Parameters
#### Query Parameters
- **method** (string) - Required - The name of the method to get information about.

### Response
#### Success Response (200)
- **result** (object) - An object containing method details.
  - **name** (string) - The name of the method.
  - **description** (string) - A description of the method.
  - **parameters** (array) - An array of method parameters.
  - **returns** (object) - Information about the method's return value.

### Response Example
{
  "result": {
    "name": "method.get",
    "description": "Retrieves detailed information about a specific Bitrix24 API method.",
    "parameters": [
      {
        "name": "method",
        "type": "string",
        "required": true,
        "description": "The name of the method to get information about."
      }
    ],
    "returns": {
      "type": "object",
      "description": "An object containing method details."
    }
  }
}
```

--------------------------------

### disk.storage.getlist

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-content.md

Retrieves a list of available storages.

```APIDOC
## disk.storage.getlist

### Description
Retrieves a list of available storages.

### Method
GET

### Endpoint
/disk/storage/getlist

### Parameters
#### Query Parameters
- **auth** (string) - Required - Authentication token.

### Response
#### Success Response (200)
- **result** (array) - List of storages.
  - **id** (integer) - Storage ID.
  - **type** (string) - Storage type.
  - **name** (string) - Storage name.

#### Response Example
{
  "result": [
    {
      "id": 1,
      "type": "user",
      "name": "My Files"
    }
  ]
}
```

--------------------------------

### IdempotencyStore for Write Replay Protection

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Implement write replay protection to prevent duplicate writes when commands are retried or replayed. Keys are derived from tenant, method, and parameters, or an explicit idempotency key. Cached responses are returned immediately on replay.

```python
import pathlib
from bitrix24_client import IdempotencyStore

store = IdempotencyStore(pathlib.Path(".runtime/idem.json"), ttl_sec=86400)

key = store.key_for(
    tenant="my-portal.bitrix24.com",
    method="crm.lead.add",
    params={"fields": {"TITLE": "Test Lead"}},
    explicit_key="form-submission-abc-123",
)

# Check for previous successful result
cached = store.check_replay(key)
if cached:
    print("Replaying cached result:", cached)
else:
    store.start(key)
    try:
        # ... make API call ...
        response = {"result": 42}
        store.done(key, response)
        print("Executed:", response)
    except Exception:
        store.clear(key)
        raise

# CLI equivalent
# python3 bitrix24_client.py crm.lead.add \
#   --params '{"fields":{"TITLE":"Test Lead"}}' \
#   --confirm-write \
#   --idempotency-key "form-submission-abc-123"
```

--------------------------------

### Run Smoke Tests for Bitrix24 Client

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Execute basic smoke tests to verify the Bitrix24 client connection and functionality for user and lead operations.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}'
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.list --params '{"select":["ID","TITLE"],"start":0}'
```

--------------------------------

### FileRateLimiter for Cross-Process Token Bucket

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Implement a file-backed token bucket rate limiter that is safe for multi-worker or multi-process deployments. Stale per-key state is auto-cleaned after TTL.

```python
import pathlib
from bitrix24_client import FileRateLimiter, Bitrix24Client, TenantConfig

limiter = FileRateLimiter(
    pathlib.Path(".runtime/rate_limiter.json"),
    rate_per_sec=2.0,   # 2 requests/second sustained
    burst=10.0,         # allow burst up to 10 tokens
    state_ttl_sec=3600, # clean stale tenant keys after 1 hour
)

tenant = TenantConfig(
    domain="my-portal.bitrix24.com",
    auth_mode="webhook",
    webhook_user_id="1",
    webhook_code="secret",
)
client = Bitrix24Client(tenant, rate_limiter=limiter)

# Rate limiter is called automatically before each request.
# To configure via env without code changes:
# export B24_RATE_LIMITER=file
# export B24_RATE_LIMITER_RATE=2.0
# export B24_RATE_LIMITER_BURST=10
```

--------------------------------

### Add a Lead via Python Client

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Use the `client.call` method to add a new lead. For write operations, ensure appropriate confirmation mechanisms are in place if not running in a trusted environment.

```python
response = client.call("crm.lead.add", params={
    "fields": {
        "TITLE": "AI Agent Lead",
        "NAME": "Test",
        "PHONE": [{"VALUE": "+1555000123", "VALUE_TYPE": "WORK"}],
        "SOURCE_ID": "WEB",
    }
})
print(response["result"])  # 42  (new lead ID)
```

--------------------------------

### Pack-Enabled CLI Usage

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

How to use the CLI with specific packs enabled, either for a single call or globally via environment variables.

```APIDOC
## Pack-enabled CLI usage

Default active pack: `core`.

List packs:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}' --list-packs
```

Enable additional packs for current call:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py im.message.add \
  --params '{"DIALOG_ID":"chat1","MESSAGE":"hello"}' \
  --packs core,comms \
  --confirm-write
```

Enable packs globally in env:

```bash
export B24_PACKS="core,comms"
```

Disable packs and rely only on explicit allowlist:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py user.current --params '{}' --packs none --method-allowlist 'user.*'
```

Diagnostics pack example:

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py method.get \
  --params '{"name":"crm.lead.add"}' \
  --packs core,diagnostics
```
```

--------------------------------

### Core Utility Methods

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/bitrix24.md

A list of essential utility methods for retrieving user and department information.

```APIDOC
## Core utility

- `user.current`
- `user.get`
- `department.get`
```

--------------------------------

### Create Execution Plan for Lead Add Operation

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Phase 1 of the two-phase execution flow. This command generates an inspectable JSON plan for a write operation without executing it. The plan includes a unique `plan_id` and an `expires_at` timestamp.

```bash
# Phase 1: create plan (no API call)
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"Plan Demo","NAME":"Staged"}}' \
  --packs core \
  --plan-only
# Output:
# {
#   "plan": {
#     "plan_id": "a1b2c3d4e5f6g7h8i9j0",
#     "method": "crm.lead.add",
#     "params": {"fields": {"TITLE": "Plan Demo", "NAME": "Staged"}},
#     "risk": "write",
#     "expires_at": 1700000000
#   },
#   "next": {
#     "execute_command": "python3 skills/bitrix24-agent/scripts/bitrix24_client.py --execute-plan a1b2c3d4e5f6g7h8i9j0"
#   }
# }
```

--------------------------------

### Iterate Through All Leads with client.iter_list()

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Use `client.iter_list` for comprehensive data retrieval, ensuring all pages of results are fetched. This is essential for data export or synchronization tasks.

```python
all_leads = []
for lead in client.iter_list(
    "crm.lead.list",
    params={"select": ["ID", "TITLE", "DATE_CREATE"], "filter": {"STATUS_ID": "NEW"}},
):
    all_leads.append(lead)
    print(f"Lead {lead['ID']}: {lead['TITLE']}")

print(f"Total fetched: {len(all_leads)}")
# Lead 10: Acme Demo
# Lead 11: Beta Corp
# ...
# Total fetched: 347
```

--------------------------------

### Configure Shared Portal Rate Limiter

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Configure the shared portal rate limiter using environment variables. Specify the type, rate, and burst parameters.

```bash
export B24_RATE_LIMITER="file"
export B24_RATE_LIMITER_RATE="2.0"
export B24_RATE_LIMITER_BURST="10"
```

--------------------------------

### Run Integration Smoke Tests

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Set the B24_RUN_INTEGRATION environment variable to '1' to enable live integration tests. Run the tests using Python 3 and the unittest module.

```bash
export B24_RUN_INTEGRATION="1"
python3 -m unittest tests.test_integration_smoke -v
```

--------------------------------

### Two-Phase Write Flow for Safer Execution

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

Implement a two-phase write flow for safer execution. First, plan the write operation, then execute the generated plan. This is recommended for write/destructive calls.

```bash
python3 skills/bitrix24-agent/scripts/bitrix24_client.py crm.lead.add \
  --params '{"fields":{"TITLE":"Plan demo"}}' \
  --plan-only

python3 skills/bitrix24-agent/scripts/bitrix24_client.py \
  --execute-plan <plan_id_from_previous_output> \
  --confirm-write
```

--------------------------------

### Product Management

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-commerce.md

Methods for managing catalog products.

```APIDOC
## catalog.product.list

### Description
Retrieves a list of catalog products.

### Method
GET

### Endpoint
/api/catalog/product/list

### Parameters
#### Query Parameters
- **filter** (object) - Optional - Filter criteria for products.
- **select** (array) - Optional - Fields to include in the response.
- **order** (object) - Optional - Sorting order.
- **start** (integer) - Optional - The index of the first record to retrieve.

### Response
#### Success Response (200)
- **result** (array) - An array of product objects.

### Response Example
```json
{
  "result": [
    {
      "ID": "101",
      "NAME": "Product A",
      "PRICE": "10.00"
    }
  ]
}
```
```

```APIDOC
## catalog.product.add

### Description
Adds a new catalog product.

### Method
POST

### Endpoint
/api/catalog/product/add

### Parameters
#### Request Body
- **fields** (object) - Required - Fields for the new product.

### Request Example
```json
{
  "fields": {
    "NAME": "New Product",
    "PRICE": "25.00"
  }
}
```

### Response
#### Success Response (200)
- **result** (string) - The ID of the newly created product.

### Response Example
```json
{
  "result": "150"
}
```
```

```APIDOC
## catalog.product.update

### Description
Updates an existing catalog product.

### Method
POST

### Endpoint
/api/catalog/product/update

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the product to update.
- **fields** (object) - Required - Fields to update.

### Request Example
```json
{
  "id": "150",
  "fields": {
    "PRICE": "30.00"
  }
}
```

### Response
#### Success Response (200)
- **result** (boolean) - True if the update was successful.

### Response Example
```json
{
  "result": true
}
```
```

--------------------------------

### Pack Selection Matrix

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/README.md

A matrix showing the recommended pack for different Bitrix24 functionalities.

```APIDOC
## Pack Selection Matrix

| Goal | Pack |
|---|---|
| CRM leads/deals/tasks/events | `core` |
| Chats, bots, messaging, telephony | `comms` |
| Bizproc/robots/templates | `automation` |
| Workgroups/feed collaboration | `collab` |
| Files/disk/doc generation | `content` |
| Scrum/board actions | `boards` |
| Orders/payments/products/catalog | `commerce` |
| Booking/calendar/time tracking | `services` |
| AI engines/entity/biconnector | `platform` |
| Landing/site/page management | `sites` |
| Consent and sign-b2e tails | `compliance` |
| Method/scope/events diagnostics | `diagnostics` |
```

--------------------------------

### Add Robot

Source: https://github.com/vrtalex/bitrix24-skill/blob/main/skills/bitrix24-agent/references/catalog-automation.md

Adds a new business process robot. Requires 'write' permissions.

```APIDOC
## bizproc.robot.add

### Description
Adds a new business process robot.

### Method
POST

### Endpoint
/api/bizproc.robot.add

### Parameters
#### Query Parameters
- **auth** (string) - Required - Authentication token.

#### Request Body
- **robot_data** (object) - Required - Data for the new robot.
  - **ENTITY_ID** (string) - Required - The ID of the entity the robot is associated with.
  - **NAME** (string) - Required - The name of the robot.
  - **CODE** (string) - Required - The code of the robot.
  - **PROPERTIES** (object) - Optional - Properties of the robot.

### Request Example
```json
{
  "auth": "your_auth_token",
  "robot_data": {
    "ENTITY_ID": "list_section",
    "NAME": "New Approval Robot",
    "CODE": "approval_robot",
    "PROPERTIES": {}
  }
}
```

### Response
#### Success Response (200)
- **result** (string) - The ID of the newly added robot.

#### Response Example
```json
{
  "result": "202"
}
```
```

--------------------------------

### Set Global Default Capability Packs via Environment Variable

Source: https://context7.com/vrtalex/bitrix24-skill/llms.txt

Configure the default capability packs for all subsequent CLI calls by setting the `B24_PACKS` environment variable.

```bash
# Set global default packs via env
export B24_PACKS="core,commerce"
python3 skills/bitrix24-agent/scripts/bitrix24_client.py sale.order.list \
  --params '{"select":["ID","ACCOUNT_NUMBER"]}'
```