### App Installation Endpoint (Bash)

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Handles Bitrix24 application installation by receiving OAuth credentials and portal information. Stores installation data in the database. Requires a POST request with JSON payload.

```bash
# Register app installation
curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d '{
    "DOMAIN": "example.bitrix24.com",
    "PROTOCOL": 1,
    "LANG": "en",
    "APP_SID": "app_sid_value",
    "AUTH_ID": "27exx66815",
    "AUTH_EXPIRES": 3600,
    "REFRESH_ID": "176xxxe",
    "REFRESH_TOKEN": "176xxxe",
    "member_id": "a3xxx22",
    "user_id": 1,
    "status": "L",
    "appVersion": 1,
    "appCode": "my_app",
    "appId": 123,
    "LICENSE": "demo",
    "LICENSE_FAMILY": "demo",
    "PLACEMENT": "DEFAULT",
    "PLACEMENT_OPTIONS": {}
  }'

# Response
{
  "message": "Installation successful"
}
```

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

### POST /api/install

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Installs the application by receiving Bitrix24 installation data.

```APIDOC
## POST /api/install

### Description

Handles the initial installation of the application by receiving and storing Bitrix24 specific data.

### Method

POST

### Endpoint

`/api/install`

### Parameters

#### Request Body

- **DOMAIN** (string) - Required - The domain of the Bitrix24 portal.
- **PROTOCOL** (string) - Required - The protocol used (e.g., 'https').
- **LANG** (string) - Required - The language code.
- **APP_SID** (string) - Required - The application SID.
- **AUTH_ID** (string) - Required - The authorization ID.
- **AUTH_EXPIRES** (number) - Required - The expiration time for the authorization token.
- **REFRESH_ID** (string) - Required - The refresh token ID.
- **member_id** (string) - Required - The member ID of the user.
- **user_id** (string) - Required - The user ID.
- **PLACEMENT** (string) - Required - The placement context.
- **PLACEMENT_OPTIONS** (string) - Required - JSON string of placement options.

### Response

#### Success Response (200)

- **message** (string) - A confirmation message indicating successful installation.

### Request Example

```bash
curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":"1","PLACEMENT":"DEFAULT","PLACEMENT_OPTIONS":"{\"any\":\"6/\"}"}'
```
```

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

### Python Backend Setup without Docker

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Commands to set up a Python backend environment locally. This includes creating a virtual environment, activating it, installing dependencies, running database migrations, and starting the development server.

```bash
cd backends/python/api
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate --noinput
python manage.py runserver 0.0.0.0:8000
```

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

### Install Bitrix24 App (cURL)

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Example using cURL to send a POST request to the /api/install endpoint. This endpoint is used during the initial installation of the Bitrix24 application and requires specific payload data.

```bash
curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d '{"AUTH_ID":"27exx66815","AUTH_EXPIRES":3600,"REFRESH_ID":"176xxxe","member_id":"a3xxx22","user_id":"1","PLACEMENT":"DEFAULT","PLACEMENT_OPTIONS":"{\"any\":\"6/\"}"}'
```

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

### Initialize Bitrix24 AI Starter Project

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/scripts/README.md

The `dev-init.sh` script performs a full project initialization using a two-phase Docker launch. It manages Ngrok authtoken, allows backend selection (PHP, Python, Node.js), handles version-aware initialization, cleans up unused project folders, and prepares the database. It resolves a 'chicken and egg' problem by first starting Ngrok to get a public URL, updating environment variables, and then restarting the entire stack.

```bash
# Preferred via Makefile
make dev-init

# Direct call
./scripts/dev-init.sh
```

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

### App Installation Endpoint

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Handles the process of installing a Bitrix24 application by receiving necessary credentials and portal details, then storing this information securely.

```APIDOC
## POST /api/install

### Description
Handles Bitrix24 application installation. Receives OAuth credentials and portal information, stores installation data in the database.

### Method
POST

### Endpoint
/api/install

### Parameters
#### Request Body
- **DOMAIN** (string) - Required - The Bitrix24 portal domain.
- **PROTOCOL** (integer) - Required - The protocol used (e.g., 1 for HTTPS).
- **LANG** (string) - Required - The language code for the portal.
- **APP_SID** (string) - Required - The application's unique identifier.
- **AUTH_ID** (string) - Required - The authorization token.
- **AUTH_EXPIRES** (integer) - Required - The expiration time of the authorization token in seconds.
- **REFRESH_ID** (string) - Required - The refresh token ID.
- **REFRESH_TOKEN** (string) - Required - The refresh token.
- **member_id** (string) - Required - The member ID of the portal.
- **user_id** (integer) - Required - The ID of the user performing the installation.
- **status** (string) - Required - The installation status.
- **appVersion** (integer) - Required - The version of the application being installed.
- **appCode** (string) - Required - The application's code name.
- **appId** (integer) - Required - The application's unique ID.
- **LICENSE** (string) - Required - The license type.
- **LICENSE_FAMILY** (string) - Required - The license family.
- **PLACEMENT** (string) - Required - The placement of the application.
- **PLACEMENT_OPTIONS** (object) - Optional - Additional options for the placement.

### Request Example
```bash
curl -X POST http://localhost:8000/api/install \
  -H "Content-Type: application/json" \
  -d 
  '{
    "DOMAIN": "example.bitrix24.com",
    "PROTOCOL": 1,
    "LANG": "en",
    "APP_SID": "app_sid_value",
    "AUTH_ID": "27exx66815",
    "AUTH_EXPIRES": 3600,
    "REFRESH_ID": "176xxxe",
    "REFRESH_TOKEN": "176xxxe",
    "member_id": "a3xxx22",
    "user_id": 1,
    "status": "L",
    "appVersion": 1,
    "appCode": "my_app",
    "appId": 123,
    "LICENSE": "demo",
    "LICENSE_FAMILY": "demo",
    "PLACEMENT": "DEFAULT",
    "PLACEMENT_OPTIONS": {}
  }'
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful installation.

#### Response Example
```json
{
  "message": "Installation successful"
}
```
```

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

### Dockerfile Quick Tour

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

An overview of the Dockerfile stages used in the project. It explains the purpose of the 'base', 'dev', and 'prod' stages, including installed packages and how the application is run in each environment.

```dockerfile
# base: python:3.11-slim, installs postgresql-client and Python deps.
# dev: mounts the project as a volume and runs runserver after migrations.
# prod: copies source into the image and starts Gunicorn (gunicorn wsgi:application --bind 0.0.0.0:8000).
```

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

### Bitrix24 Batch and Single API Calls with Frontend Example

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Illustrates how to interact with the Bitrix24 API from a frontend application using a provided framework (Nuxt.js in this example). It shows how to initialize the Bitrix24 frame, execute multiple API calls concurrently using `callBatch` for efficiency, perform single API calls with `callMethod`, and retrieve authentication data needed for backend requests.

```typescript
// Frontend batch request example
const { $initializeB24Frame } = useNuxtApp()
const $b24: B24Frame = await $initializeB24Frame()

// Execute batch of API calls
const response = await $b24.callBatch({
  appInfo: { method: 'app.info' },
  profile: { method: 'profile' },
  deals: {
    method: 'crm.deal.list',
    params: { filter: { STAGE_ID: 'NEW' }, select: ['ID', 'TITLE'] }
  },
  contacts: {
    method: 'crm.contact.list',
    params: { select: ['ID', 'NAME', 'LAST_NAME'] }
  }
})

const data = response.getData()
// data.appInfo, data.profile, data.deals, data.contacts

// Single method call
const result = await $b24.callMethod('crm.deal.get', { id: 123 })

// Get auth data for backend requests
const authData = $b24.auth.getAuthData()
// { domain, access_token, refresh_token, expires_in, member_id }

```

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

### Start PHP Development Stack

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/scripts/README.md

This command starts the PHP services for daily development.

```bash
make dev-php
```

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

### POST /api/install

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Creates or updates an `ApplicationInstallation` record for the Bitrix24 portal.

```APIDOC
## POST /api/install

### Description
Creates or updates an `ApplicationInstallation` record for the Bitrix24 portal using fields from `request.bitrix24_account`.

### Method
POST

### Endpoint
/api/install

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **portal_domain** (string) - The domain of the Bitrix24 portal.
- **member_id** (string) - The member ID of the Bitrix24 portal.
- **auth_data** (object) - Authentication related data.
  - **access_token** (string) - The access token.
  - **refresh_token** (string) - The refresh token.
  - **expires_in** (integer) - The expiration time in seconds.

### Request Example
```json
{
  "portal_domain": "yourcompany.bitrix24.com",
  "member_id": "abcdef123456",
  "auth_data": {
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "expires_in": 3600
  }
}
```

### Response
#### Success Response (200 or 201)
- **message** (string) - Confirmation of installation or update.

#### Response Example
```json
{
  "message": "Application installed/updated successfully."
}
```
```

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

### Node.js Backend Event Registration Example

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Describes the backend setup for event handling in Node.js. It involves exposing a public `/api/app-events` endpoint and performing payload validation, keeping the handler accessible without JWT.

```javascript
expose /api/app-events, validate payload, keep it public.
```

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

### GET /api/list

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Fetches a static list of items.

```APIDOC
## GET /api/list

### Description
Returns a static list of items.

### Method
GET

### Endpoint
/api/list

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **items** (array) - A list of items.

#### Response Example
```json
{
  "items": [
    {
      "id": 1,
      "name": "Item 1"
    },
    {
      "id": 2,
      "name": "Item 2"
    }
  ]
}
```
```

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

### GET /api

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Provides a simple response indicating that the Python backend is running.

```APIDOC
## GET /api

### Description
Quick "Python Backend is running" response.

### Method
GET

### Endpoint
/api

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "message": "Python Backend is running"
}
```
```

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

### Install @bitrix24/b24jssdk using npm

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/bitrix24-js-sdk.md

Installs the Bitrix24 JavaScript SDK using npm. This is the primary method for Node.js and frontend projects.

```bash
npm install @bitrix24/b24jssdk
```

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

### Troubleshoot Container Startup Failures

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/scripts/README.md

Commands to resolve issues where containers refuse to start, involving stopping all services, cleaning up, and re-initializing the environment.

```bash
make down
make clean
make dev-init
```

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

### Initialize and Run Development Environment (Bash)

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Commands to initialize and run the development environment. Includes automatic setup, manual backend selection (PHP, Python, Node.js), stopping containers, building for production, and security scanning.

```bash
# Automatic initialization wizard
make dev-init

# Manual setup - choose one backend
cp .env.example .env
make dev-php      # PHP backend
make dev-python   # Python backend
make dev-node     # Node.js backend

# Stop all containers
make down

# Production builds
make prod-php
make prod-python
make prod-node

# Security scanning
make security-scan
make security-tests
```

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

### Install Dependencies for Node.js RabbitMQ

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/queues/node.md

Installs the 'amqplib' library for RabbitMQ communication and development dependencies like 'typescript' and 'tsx' for TypeScript projects.

```bash
pnpm add amqplib
pnpm add -D typescript tsx @types/node
```

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

### GET /api/enum

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Retrieves a static list of predefined options or enumerations.

```APIDOC
## GET /api/enum

### Description
Returns a static list of options.

### Method
GET

### Endpoint
/api/enum

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **options** (array) - A list of available options.

#### Response Example
```json
{
  "options": [
    "option1",
    "option2",
    "option3"
  ]
}
```
```

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

### GET /api/health

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/knowledge.md

Performs a health check and returns the current status along with a timestamp.

```APIDOC
## GET /api/health

### Description
Health-check endpoint that returns the current status and a timestamp.

### Method
GET

### Endpoint
/api/health

### Parameters
#### Path Parameters
None

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The health status (e.g., "ok").
- **timestamp** (string) - The current timestamp.

#### Response Example
```json
{
  "status": "ok",
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

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

### Backend Startup Commands

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Provides the `make` commands to start the different backend services (PHP, Python, Node.js) independently using Docker Compose profiles. These commands are essential for running the application locally.

```bash
make dev-php      # PHP backend
make dev-python   # Python backend
make dev-node     # Node backend
```

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

### Importing Icons from Bitrix24 Icons Vue

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/knowledge.md

This example shows how to import specific icons from the `@bitrix24/b24icons-vue` package. Icons are organized by category, allowing for efficient and targeted imports.

```javascript
import IconName from '@bitrix24/b24icons-vue/category/IconName';
```

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

### Use API Store for Data Management

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Shows how to initialize and use the API store, which is part of the frontend structure. It includes initializing the store with the Bitrix24 SDK instance and fetching data using `getList`. It also provides an example of making a custom API call with JWT authentication.

```typescript
const apiStore = useApiStore()
await apiStore.init($b24)
const list = await apiStore.getList()

const myMethod = async (): Promise<MyType> => {
  return $api('/api/my-endpoint', {
    headers: { Authorization: `Bearer ${tokenJWT.value}` },
  })
}
```

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

### Project Directory Layout

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Illustrates the file and directory structure of the Bitrix24 AI Starter Kit, showing the organization of frontend, backend options, infrastructure, and other project components.

```tree
starter-kit/
├── frontend/               # Nuxt 3 + Vue 3 frontend
├── backends/               # Three backend options
│   ├── php/                # Symfony + PHP SDK
│   ├── python/             # Django + b24pysdk
│   └── node/               # Express + Node.js
├── infrastructure/
│   └── database/           # PostgreSQL init scripts
├── instructions/           # AI agent guides
└── logs/                   # Host-mounted logs
```

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

### Version Management Scripts (Bash)

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Provides bash scripts and make commands for managing multiple versions of the application. These scripts allow for creating new versions by cloning the project, deleting existing versions, and initializing development environments with a specific version. Versions are stored in the `versions/` directory.

```bash
# Create a new version (clones current project to versions/v2)
./scripts/create-version.sh v2
# or
make create-version VERSION=v2

# Delete a version
./scripts/delete-version.sh v2
# or
make delete-version VERSION=v2

# Initialize development with specific version
DEV_INIT_VERSION=v2 make dev-init
# or
./scripts/dev-init.sh --version v2

# Versions are stored in versions/ directory
# Each version is a complete project copy
```

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

### Configure Tailwind CSS with Vite in Nuxt.js

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/knowledge.md

This snippet shows how to integrate Tailwind CSS into a Nuxt.js project using the Vite plugin. It requires installing `@tailwindcss/vite` and configuring `nuxt.config.ts` to include the plugin. The CSS import in `assets/css/main.css` is also demonstrated.

```typescript
import tailwindcss from '@tailwindcss/vite'
export default defineNuxtConfig({
  vite: { plugins: [tailwindcss()] }
})
```

```css
@import 'tailwindcss';
@import '@bitrix24/b24ui-nuxt';

@theme static {
  /* custom utilities */
}
```

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

### Recommended Tooling for Python Code Quality

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/code-review.md

Lists essential command-line tools for maintaining Python code quality, including linters (flake8, pylint), formatters (black), type checkers (mypy), and import sorters (isort), with installation and usage examples.

```bash
# 1. flake8 — PEP 8 compliance
pip install flake8
flake8 your_file.py

# 2. pylint — stricter linting
pip install pylint
pylint your_file.py

# 3. black — auto-formatting
pip install black
black your_file.py --check

# 4. mypy — static typing checks
pip install mypy
mypy your_file.py

# 5. isort — import sorting
pip install isort
isort your_file.py --check-only
```

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

### Initialize and Use Bitrix24 JS SDK

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Demonstrates how to initialize the Bitrix24 JS SDK within a Nuxt application, perform batch and single method calls, retrieve authentication data, and open a slider. This is crucial for interacting with the Bitrix24 environment from the frontend.

```typescript
const { $initializeB24Frame } = useNuxtApp()
const $b24 = await $initializeB24Frame()
const batch = await $b24.callBatch({ appInfo: { method: 'app.info' } })
const single = await $b24.callMethod('method.name', { param: 'value' })
const auth = $b24.auth.getAuthData()
await $b24.slider.openPath('/path')
```

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

### Initialize Development Environment

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/scripts/README.md

This command performs a full project bootstrap, setting up the development environment for the first launch.

```bash
make dev-init
```

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

### Initialize Bitrix24 Frame and Call SDK Methods

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Demonstrates how to initialize the Bitrix24 frame using Nuxt's composables and then interact with the Bitrix24 JS SDK. Includes examples of calling batch requests, single methods, and opening a slider.

```typescript
const { $initializeB24Frame } = useNuxtApp()
const $b24: B24Frame = await $initializeB24Frame()

const batch = await $b24.callBatch({
  appInfo: { method: 'app.info' },
  profile: { method: 'profile' }
})
const data = batch.getData()

const result = await $b24.callMethod('method.name', { param: 'value' })
const authData = $b24.auth.getAuthData()

await $b24.slider.openPath('/path/to/page')
```

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

### Debugging with Make and Docker Commands

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Provides essential command-line interface (CLI) helpers for debugging the project using Make and Docker. This includes viewing logs and checking service health.

```bash
make logs
docker logs api --tail 50
docker logs frontend --tail 50
curl http://localhost:8000/api/health

```

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

### Initialize and use B24Helper and Pull Client

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/bitrix24-js-sdk.md

Demonstrates initializing the B24Helper for accessing profile, app, and currency data, and setting up the Pull Client for real-time event subscriptions.

```typescript
import { useB24Helper, LoadDataType } from '@bitrix24/b24jssdk'
const helperApi = useB24Helper()
const $b24 = await initializeB24Frame()
await helperApi.initB24Helper($b24, [LoadDataType.Profile, LoadDataType.App, LoadDataType.Currency])
const profile = helperApi.getB24Helper().profileInfo.data
helperApi.useSubscribePullClient(msg => console.log(msg), 'application')
helperApi.startPullClient()
```

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

### Minimal B24Table Setup (Vue)

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/table-and-grid.md

Demonstrates the basic configuration of B24Table with columns and data. This setup is suitable for simple data display without advanced features.

```vue
<template>
  <B24Table :columns="columns" :data="rows" />
</template>

<script setup>
const columns = [
  { key: 'id', header: 'ID' },
  { key: 'name', header: 'Name' },
]
const rows = ref([
  { id: 1, name: 'Record 1' },
  { id: 2, name: 'Record 2' },
])
</script>
```

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

### Install Symfony Messenger and AMQP Extension

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/queues/php.md

Installs the necessary Symfony Messenger component and the AMQP extension for RabbitMQ communication using Composer. This is a prerequisite for using RabbitMQ with Symfony Messenger.

```bash
composer require symfony/messenger enqueue/amqp-ext
```

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

### Example of Request for Clarification in Code Review

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/code-review.md

Shows an example of a code reviewer asking for clarification on a function's purpose to determine the appropriate action regarding documentation.

```text
⚠ Function `add(a, b)` has no docstring.
Is this part of the public API or an internal helper?
- If public: add a docstring.
- If internal: consider renaming to `_add` or document why it can stay.
What should we do?
```

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

### Environment Variables Configuration

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Shows example environment variable configurations for PHP, Python, and Node.js backends, including essential parameters like server host, Bitrix24 app credentials, scopes, and database settings. It also highlights the mandatory NGROK_AUTHTOKEN.

```env
# PHP backend
SERVER_HOST=http://api-php:8000
CLIENT_ID=local.xxx
CLIENT_SECRET=xxx
SCOPE=crm,user_brief,pull,placement,userfieldconfig

# Python backend
SERVER_HOST=http://api-python:8000
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@example.com
DJANGO_SUPERUSER_PASSWORD=admin123
CLIENT_ID=local.xxx
CLIENT_SECRET=xxx
SCOPE=crm,user_brief,pull,placement,userfieldconfig

# Node backend
SERVER_HOST=http://api-node:8000
CLIENT_ID=local.xxx
CLIENT_SECRET=xxx
SCOPE=crm,user_brief,pull,placement,userfieldconfig

Shared values:
DB_NAME=appdb
DB_USER=appuser
DB_PASSWORD=apppass
NGROK_AUTHTOKEN=your_authtoken_here
VIRTUAL_HOST=https://your-domain.ngrok-free.app  # filled after Ngrok launches
```

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

### GET /api/list

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Retrieves a general list of items.

```APIDOC
## GET /api/list

### Description

Fetches a general list of items.

### Method

GET

### Endpoint

`/api/list`

### Response

#### Success Response (200)

- An array of strings representing list items (`string[]`).

### Request Example

```bash
curl http://localhost:8000/api/list
```
```

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

### Backend API Integration for Settings (TypeScript)

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/settings-page.md

Example TypeScript functions for interacting with a backend API to load and save settings. These functions use the Fetch API and assume a RESTful endpoint structure for managing section-specific settings.

```typescript
const loadSettings = sectionId => fetch(`/api/settings/${sectionId}`).then(res => res.json())
const saveSettings = (sectionId, data) => fetch(`/api/settings/${sectionId}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(data),
})
```

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

### Environment Configuration Variables (.env)

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Lists the required environment variables for production deployment. This includes JWT secrets, database credentials, Bitrix24 application credentials, the public URL of the application, build target settings, and optional RabbitMQ configuration.

```bash
# .env
# JWT secret for token signing (REQUIRED)
JWT_SECRET=your-secret-key-minimum-32-characters

# Database credentials
DB_HOST=database
DB_PORT=5432
DB_NAME=appdb
DB_USER=appuser
DB_PASSWORD=secure-password

# Bitrix24 App credentials (from vendors.bitrix24.com)
CLIENT_ID=your_app_client_id
CLIENT_SECRET=your_app_client_secret
SCOPE=crm,user_brief,pull,placement,userfieldconfig

# Public URL (Ngrok or production domain)
VIRTUAL_HOST=https://your-domain.ngrok-free.app

# Build target (dev or production)
BUILD_TARGET=production

# RabbitMQ (optional)
RABBITMQ_USER=queue_user
RABBITMQ_PASSWORD=queue_password

```

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

### GET /api/enum

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Retrieves a list of enumeration values.

```APIDOC
## GET /api/enum

### Description

Fetches a list of available enumeration values.

### Method

GET

### Endpoint

`/api/enum`

### Response

#### Success Response (200)

- An array of strings representing enumeration values (`string[]`).

### Request Example

```bash
curl http://localhost:8000/api/enum
```
```

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

### Add Protected API Endpoints in PHP, Python, and Node.js

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Demonstrates how to create custom, protected API endpoints in various backend frameworks. These examples show how to handle requests, access authentication data (like JWT payloads or Bitrix24 clients), and return JSON responses. They are designed to be integrated into existing backend applications.

```php
<?php
namespace App\Controller;

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;

class ApiController extends AbstractController
{
    #[Route('/api/my-endpoint', name: 'api_my_endpoint', methods: ['GET'])]
    public function myEndpoint(Request $request): JsonResponse
    {
        // JWT payload set by JwtAuthenticationListener
        $jwtPayload = $request->attributes->get('jwt_payload');

        try {
            // Your business logic here
            return new JsonResponse([
                'data' => 'custom response',
                'user' => $jwtPayload['domain'] ?? null
            ]);
        } catch (\Throwable $e) {
            return new JsonResponse(['error' => $e->getMessage()], 500);
        }
    }
}

```

```python
from django.http import JsonResponse
from django.views.decorators.http import require_GET
from django.views.decorators.clickjacking import xframe_options_exempt
from .utils.decorators import auth_required, log_errors
from .utils import AuthorizedRequest

@xframe_options_exempt
@require_GET
@log_errors("my_endpoint")
@auth_required
def my_endpoint(request: AuthorizedRequest):
    # Access Bitrix24 client from request
    client = request.bitrix24_account.client

    # Call Bitrix24 API
    response = client._bitrix_token.call_method(
        api_method='crm.deal.list',
        params={'filter': {'STAGE_ID': 'NEW'}}
    )

    return JsonResponse({
        'data': 'custom response',
        'deals': response.get('result', [])
    })

```

```javascript
import express from 'express';
import verifyToken from './utils/verifyToken.js';

const app = express();
app.use(express.json());

app.get('/api/my-endpoint', verifyToken, async (req, res) => {
  try {
    // Access decoded JWT from middleware
    const jwtPayload = req.user;

    // Your business logic here
    res.json({
      data: 'custom response',
      userId: jwtPayload.id
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

```

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

### Minimal B24Form Example

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/front/form.md

A basic example demonstrating the usage of B24Form to create a simple form with a title input field and a submit button. It utilizes reactive state management and an onSubmit handler for form submission.

```vue
<template>
  <B24Form :state="state" @submit="onSubmit">
    <B24FormField label="Title" name="title">
      <B24Input v-model="state.title" />
    </B24FormField>

    <B24Button type="submit" color="air-primary">
      Save
    </B24Button>
  </B24Form>
</template>

<script setup>
const state = reactive({ title: '' })
const onSubmit = async data => console.log('Submitted', data)
</script>
```

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

### Docker Compose Configuration for Multi-Service Deployment (YAML)

Source: https://context7.com/bitrix24/b24-ai-starter/llms.txt

Defines a multi-service Docker setup using Docker Compose. It includes a PostgreSQL database, an optional RabbitMQ message broker, and selectable backend profiles (frontend, node). This configuration allows for flexible development and deployment environments.

```yaml
# docker-compose.yml
services:
  database:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: ${DB_NAME:-appdb}
      POSTGRES_USER: ${DB_USER:-appuser}
      POSTGRES_PASSWORD: ${DB_PASSWORD:-apppass}
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-appuser}"]
      interval: 5s
      timeout: 5s
      retries: 5

  frontend:
    profiles: ["frontend"]
    build:
      context: ./frontend
      target: ${BUILD_TARGET:-dev}
    environment:
      NUXT_PUBLIC_APP_URL: ${VIRTUAL_HOST}
      NUXT_PUBLIC_API_URL: ${VIRTUAL_HOST}
    expose:
      - '3000'

  api-node:
    profiles: ["node"]
    build:
      context: ./backends/node/api
      target: ${BUILD_TARGET:-dev}
    environment:
      DB_HOST: database
      JWT_SECRET: ${JWT_SECRET}
      PORT: 8000
    ports:
      - "8000:8000"
    depends_on:
      - database

  rabbitmq:
    profiles: ["queue"]
    image: rabbitmq:3.13-management-alpine
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_USER:-queue_user}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_PASSWORD:-queue_password}
    ports:
      - "5672:5672"
      - "15672:15672"
```

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

### Start Celery Worker (Bash)

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/queues/python.md

Command to start a Celery worker using Docker Compose, specifying the Python profile and queue profile. It connects to the Celery app defined in 'api.celery.celery_app' and sets the log level to 'info'.

```bash
COMPOSE_PROFILES=python,queue docker compose --env-file .env run --rm \
  api-python celery -A api.celery.celery_app worker --loglevel=info
```

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

### GET /api/health

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/README.md

Retrieves the health status of the backend service.

```APIDOC
## GET /api/health

### Description

Checks the health status of the backend service, including backend availability and timestamp.

### Method

GET

### Endpoint

`/api/health`

### Response

#### Success Response (200)

- **status** (string) - The overall status of the service.
- **backend** (string) - The status of the backend component.
- **timestamp** (number) - The current timestamp.

### Request Example

```bash
curl http://localhost:8000/api/health
```
```

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

### Environment Variables Configuration

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Lists essential environment variables required for the Bitrix24 AI Starter project. These variables cover NGROK authentication, server host, virtual host, database credentials, Bitrix24 application credentials (CLIENT_ID, CLIENT_SECRET), scopes, and Django superuser details.

```env
NGROK_AUTHTOKEN=...
SERVER_HOST=http://api-php:8000   # or api-python/api-node
VIRTUAL_HOST=https://your-domain.ngrok-free.app
DB_NAME=appdb
DB_USER=appuser
DB_PASSWORD=apppass
CLIENT_ID=local.xxx
CLIENT_SECRET=xxx
SCOPE=crm,user_brief,pull,placement,userfieldconfig
DJANGO_SUPERUSER_USERNAME=admin
DJANGO_SUPERUSER_EMAIL=admin@example.com
DJANGO_SUPERUSER_PASSWORD=admin123
```

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

### Authentication and Security

Source: https://github.com/bitrix24/b24-ai-starter/blob/main/instructions/python/bitrix24-python-sdk.md

Details on how to authenticate API requests using JWT and the flow for obtaining and using tokens.

```APIDOC
## Auth & Security

All endpoints except `/api/install` and `/api/getToken` require an `Authorization: Bearer <jwt>` header.

### Authentication Flow

1.  **`/api/install`**: Stores Bitrix24 payload (`DOMAIN`, `AUTH_ID`, `REFRESH_ID`, `member_id`, etc.). No JWT is required for this endpoint.
2.  **`/api/getToken`**: Exchanges placement data for a 1-hour JWT. No JWT is required for this endpoint.
3.  **Authenticated Endpoints**: Validate the JWT, hydrate the `bitrix24_account`, and utilize SDK clients.
```