### Quick Start: Set up and run PingCRM development environment

Source: https://docs.pingcrm.xyz/contributing

Commands to set up and run the full development environment for PingCRM on a pure-host setup. Starts supporting services with Docker Compose, installs backend dependencies, runs database migrations, starts the backend server, installs frontend dependencies, and runs tests.

```bash
# Bring up just the supporting services  
docker compose up -d postgres redis  
  
# Backend  
cd backend  
python3.12 -m venv .venv && source .venv/bin/activate  
pip install -r requirements.txt -r requirements-test.txt  
alembic upgrade head  
uvicorn app.main:app --reload  
  
# Frontend  
cd frontend && npm install && npm run dev  
  
# Tests  
cd backend && pytest  
cd frontend && npm test  

```

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

### Set up backend environment

Source: https://docs.pingcrm.xyz/setup

Sets up the Python backend environment: creates a virtual environment, activates it, installs dependencies, and copies the example environment file.

```bash
cd backend  
python3.12 -m venv .venv  
source .venv/bin/activate  # Windows: .venv\Scripts\activate  
pip install -r requirements.txt  
cp .env.example .env  
```

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

### Install and start Redis

Source: https://docs.pingcrm.xyz/setup

Installs and starts Redis on macOS or Ubuntu/Debian, then verifies with redis-cli ping expecting PONG.

```bash
# macOS  
brew install redis  
brew services start redis  
  
# Ubuntu/Debian  
sudo apt install redis-server  
sudo systemctl start redis  
  
# Verify  
redis-cli ping  # PONG  
```

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

### Docker Compose setup and migration

Source: https://docs.pingcrm.xyz/setup

Set up environment files, start all services with Docker Compose, and run database migrations. Requires editing .env to set POSTGRES_PASSWORD and SECRET_KEY.

```bash
# Configure environment variables  
cp backend/.env.example backend/.env  
cp .env.docker.example .env  
  
# Set required variables used by Docker Compose interpolation  
# Edit .env and replace POSTGRES_PASSWORD and SECRET_KEY.  
  
# Start all services  
docker compose up  
  
# Run database migrations (first time or after model changes)  
docker compose exec backend alembic upgrade head  

```

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

### Install and verify Bird CLI

Source: https://docs.pingcrm.xyz/features/twitter

Install the Bird CLI globally and verify the installation. The backend checks for Bird availability at runtime via shutil.which("bird").

```bash
npm install -g @steipete/bird@0.8.0  

```

```bash
bird --version  

```

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

### Install frontend dependencies

Source: https://docs.pingcrm.xyz/setup

Installs frontend dependencies using npm.

```bash
cd frontend  
npm install  
```

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

### Start production Docker Compose stack

Source: https://docs.pingcrm.xyz/setup

Start the production stack using pre-built images and a Caddy reverse proxy with automatic HTTPS. All configuration is via environment variables.

```bash
docker compose -f docker-compose.prod.yml up -d  

```

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

### Install test dependencies for pre-push hook

Source: https://docs.pingcrm.xyz/contributing

Installs test dependencies into the backend virtual environment, required for the pre-push hook which uses backend/.venv's Python. Run this after adding any new test dependency to requirements-test.txt.

```bash
cd backend && source .venv/bin/activate && pip install -r requirements-test.txt  

```

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

### GET /api/v1/settings/suggestions

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the suggestion engine preferences.

```APIDOC
## GET /api/v1/settings/suggestions

### Description
Get suggestion engine preferences.

### Method
GET

### Endpoint
/api/v1/settings/suggestions

### Response
#### Success Response (200)
- **suggestions** (object) - Suggestion engine preferences.

#### Response Example
{
  "suggestions": {
    "enabled": true
  }
}
```

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

### GET /api/v1/version

Source: https://docs.pingcrm.xyz/api-reference

Endpoint to get the current app version and latest GitHub release for self-hosters.

```APIDOC
## GET /api/v1/version

### Description
Current app version and latest GitHub release (for self-hoster update banner).

### Method
GET

### Endpoint
/api/v1/version
```

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

### Configure .env file

Source: https://docs.pingcrm.xyz/setup

Example .env configuration: SECRET_KEY placeholder, DATABASE_URL for PostgreSQL, and REDIS_URL for local Redis.

```bash
SECRET_KEY=<run: python -c "import secrets; print(secrets.token_urlsafe(64))">  
DATABASE_URL=postgresql+asyncpg://localhost:5432/pingcrm  
REDIS_URL=redis://localhost:6379/0  
```

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

### Clone and enter PingCRM repository

Source: https://docs.pingcrm.xyz/

Clone the PingCRM repository and navigate into the project directory to begin setup.

```bash
git clone https://github.com/sneg55/pingcrm.git  
cd pingcrm  
```

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

### GET /api/v1/settings/sync

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the current sync schedule preferences.

```APIDOC
## GET /api/v1/settings/sync

### Description
Get sync schedule preferences.

### Method
GET

### Endpoint
/api/v1/settings/sync

### Response
#### Success Response (200)
- **sync** (object) - Sync schedule preferences.

#### Response Example
{
  "sync": {
    "frequency": "daily",
    "time": "02:00"
  }
}
```

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

### POST /api/v1/auth/whatsapp/connect

Source: https://docs.pingcrm.xyz/api-reference

Starts the WhatsApp link-device flow to connect a WhatsApp session.

```APIDOC
## POST /api/v1/auth/whatsapp/connect

### Description
Start a WhatsApp link-device flow.

### Method
POST

### Endpoint
/api/v1/auth/whatsapp/connect

### Authentication
Bearer token required.

### Response
#### Success Response (200)
- **data** (object) - Contains QR code or session info.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### GET /api/v1/settings/mcp-key

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the status of the MCP API key.

```APIDOC
## GET /api/v1/settings/mcp-key

### Description
Get MCP API key status.

### Method
GET

### Endpoint
/api/v1/settings/mcp-key

### Response
#### Success Response (200)
- **status** (string) - Status of the MCP API key (e.g., active, revoked).

#### Response Example
{
  "status": "active"
}
```

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

### GET /api/v1/settings/telegram

Source: https://docs.pingcrm.xyz/api-reference

Retrieves Telegram-specific settings, such as the 2nd-tier toggle.

```APIDOC
## GET /api/v1/settings/telegram

### Description
Get Telegram-specific settings (e.g., 2nd-tier toggle).

### Method
GET

### Endpoint
/api/v1/settings/telegram

### Response
#### Success Response (200)
- **telegram** (object) - Telegram settings.

#### Response Example
{
  "telegram": {
    "secondTierEnabled": true
  }
}
```

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

### GET /api/v1/auth/whatsapp/qr

Source: https://docs.pingcrm.xyz/api-reference

Fetches the current WhatsApp QR payload for linking a device.

```APIDOC
## GET /api/v1/auth/whatsapp/qr

### Description
Fetch the current WhatsApp QR payload.

### Method
GET

### Endpoint
/api/v1/auth/whatsapp/qr

### Authentication
Bearer token required.

### Response
#### Success Response (200)
- **data** (object) - Contains the QR payload.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### GET /api/v1/settings/priority

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the follow-up intervals configured for high, medium, and low priority levels.

```APIDOC
## GET /api/v1/settings/priority

### Description
Get follow-up intervals for priority levels (high, medium, low).

### Method
GET

### Endpoint
/api/v1/settings/priority

### Response
#### Success Response (200)
- **priority** (object) - Follow-up intervals for high, medium, and low priority.

#### Response Example
{
  "priority": {
    "high": 7,
    "medium": 14,
    "low": 30
  }
}
```

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

### Endpoint with Envelope response model

Source: https://docs.pingcrm.xyz/architecture

Example endpoint using the Envelope response model. It declares response_model=Envelope[ContactRead] and returns Envelope(data=contact) for full type safety.

```python
@router.get("/contacts/{contact_id}", response_model=Envelope[ContactRead])  
async def get_contact(contact_id: uuid.UUID, db: AsyncSession = Depends(get_db)):  
    ...  
    return Envelope(data=contact)  
```

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

### Claude Desktop remote stdio via SSH configuration

Source: https://docs.pingcrm.xyz/features/mcp

Tunnels stdio over SSH to a remote PingCRM installation. Uses the ssh command with a private key and a remote command to run the MCP server.

```json
{  
  "mcpServers": {  
    "pingcrm": {  
      "command": "ssh",  
      "args": [  
        "-i", "~/.ssh/your_key",  
        "root@your-server.com",  
        "cd /opt/pingcrm && docker compose exec -T backend python -m mcp_server.server"  
      ]  
    }  
  }  
}  

```

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

### Run backend and frontend tests

Source: https://docs.pingcrm.xyz/setup

Commands to run the backend test suite with pytest and coverage reporting, then the frontend test suite with Vitest via npm.

```bash
# Backend (pytest)  
cd backend  
pytest  
pytest --cov=app --cov-report=term-missing  
  
# Frontend (Vitest)  
cd frontend  
npm test  

```

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

### GET /api/v1/contacts/tags/taxonomy

Source: https://docs.pingcrm.xyz/api-reference

Returns the tag taxonomy structure.

```APIDOC
## GET /api/v1/contacts/tags/taxonomy

### Description
Tag taxonomy structure.

### Method
GET

### Endpoint
/api/v1/contacts/tags/taxonomy

### Response
#### Success Response (200)
- **taxonomy** (object) - Taxonomy structure

#### Response Example
{
  "taxonomy": {}
}
```

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

### GET /api/v1/contacts/2nd-tier/count

Source: https://docs.pingcrm.xyz/api-reference

Returns the count of 2nd-tier contacts.

```APIDOC
## GET /api/v1/contacts/2nd-tier/count

### Description
Count of 2nd-tier contacts.

### Method
GET

### Endpoint
/api/v1/contacts/2nd-tier/count

### Response
#### Success Response (200)
- **count** (integer) - Number of 2nd-tier contacts

#### Response Example
{
  "count": 10
}
```

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

### Run database migrations

Source: https://docs.pingcrm.xyz/setup

Runs database migrations to bring the schema up to date.

```bash
alembic upgrade head  
```

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

### GET /api/v1/contacts/overdue

Source: https://docs.pingcrm.xyz/api-reference

Returns contacts with overdue follow-ups.

```APIDOC
## GET /api/v1/contacts/overdue

### Description
Overdue follow-up contacts.

### Method
GET

### Endpoint
/api/v1/contacts/overdue

### Response
#### Success Response (200)
- **overdue** (array) - List of overdue contacts

#### Response Example
{
  "overdue": []
}
```

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

### Create PostgreSQL database

Source: https://docs.pingcrm.xyz/setup

Creates the PostgreSQL database named 'pingcrm' for the project.

```bash
createdb pingcrm  
```

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

### GET /api/v1/contacts/birthdays

Source: https://docs.pingcrm.xyz/api-reference

Returns contacts with upcoming birthdays.

```APIDOC
## GET /api/v1/contacts/birthdays

### Description
Upcoming birthdays.

### Method
GET

### Endpoint
/api/v1/contacts/birthdays

### Response
#### Success Response (200)
- **birthdays** (array) - List of contacts with upcoming birthdays

#### Response Example
{
  "birthdays": []
}
```

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

### Claude Desktop local stdio configuration

Source: https://docs.pingcrm.xyz/features/mcp

Configure Claude Desktop to run the MCP server as a local subprocess using Python. No API key is needed; communication is over stdin/stdout.

```json
{  
  "mcpServers": {  
    "pingcrm": {  
      "command": "python",  
      "args": ["-m", "mcp_server.server"],  
      "cwd": "/path/to/pingcrm/backend",  
      "env": {  
        "DATABASE_URL": "postgresql+asyncpg://user:pass@localhost/pingcrm",  
        "SECRET_KEY": "your-secret-key"  
      }  
    }  
  }  
}  

```

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

### GET /api/v1/contacts/stats

Source: https://docs.pingcrm.xyz/api-reference

Provides dashboard statistics for contacts.

```APIDOC
## GET /api/v1/contacts/stats

### Description
Dashboard contact statistics.

### Method
GET

### Endpoint
/api/v1/contacts/stats

### Response
#### Success Response (200)
- **total** (integer) - Total contacts
- **active** (integer) - Active contacts

#### Response Example
{
  "total": 100,
  "active": 80
}
```

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

### GET /api/health

Source: https://docs.pingcrm.xyz/api-reference

Health check endpoint for liveness probe.

```APIDOC
## GET /api/health

### Description
Liveness probe.

### Method
GET

### Endpoint
/api/health
```

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

### System architecture diagram

Source: https://docs.pingcrm.xyz/architecture

ASCII architecture diagram showing the three-tier system: Next.js frontend communicates with FastAPI backend via REST, which uses PostgreSQL with ORM and Redis for caching and task brokering. Celery workers handle background sync, scoring, and AI suggestions.

```text
┌─────────────────┐       ┌──────────────────────┐       ┌────────────────┐  
│   Next.js 15    │──────>│   FastAPI (async)     │──────>│  PostgreSQL    │  
│   React 19      │ REST  │   Pydantic schemas    │  ORM  │  UUID PKs      │  
│   Tailwind v4   │<──────│   JWT auth            │<──────│  GIN indexes   │  
└─────────────────┘       └──────────┬───────────┘       └────────────────┘  
                                     │  
                          ┌──────────▼───────────┐  
                          │   Redis              │  
                          │   - Celery broker    │  
                          │   - Rate gates       │  
                          │   - Tweet cache      │  
                          │   - OAuth nonces     │  
                          └──────────┬───────────┘  
                                     │  
                          ┌──────────▼───────────┐  
                          │   Celery Workers     │  
                          │   - Gmail sync       │  
                          │   - Telegram sync    │  
                          │   - Twitter polling  │  
                          │   - Score refresh    │  
                          │   - AI suggestions   │  
                          └──────────────────────┘  
```

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

### POST /api/v1/contacts/sync/google

Source: https://docs.pingcrm.xyz/api-reference

Initiates a background import from Google Contacts. Returns immediately; a notification fires when the task completes.

```APIDOC
## POST /api/v1/contacts/sync/google

### Description
Import from Google Contacts.

### Method
POST

### Endpoint
/api/v1/contacts/sync/google

### Response
#### Success Response (200)
- **status** (string) - Status of sync

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

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

### POST /api/v1/auth/login

Source: https://docs.pingcrm.xyz/api-reference

Authenticates a user with email and password, returning a token.

```APIDOC
## POST /api/v1/auth/login

### Description
Login with email and password.

### Method
POST

### Endpoint
/api/v1/auth/login

### Authentication
Not required (public endpoint).

### Request Body
- **email** (string) - Required - The email address of the user.
- **password** (string) - Required - The password of the user.

### Response
#### Success Response (200)
- **data** (object) - Contains authentication token and user information.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### POST /api/v1/auth/google/callback

Source: https://docs.pingcrm.xyz/api-reference

Handles the Google OAuth callback to complete authentication.

```APIDOC
## POST /api/v1/auth/google/callback

### Description
Handle the Google OAuth callback.

### Method
POST

### Endpoint
/api/v1/auth/google/callback

### Authentication
Not required (public endpoint).

### Request Body
- **code** (string) - Required - The authorization code from Google.

### Response
#### Success Response (200)
- **data** (object) - Contains authentication result.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### GET /api/v1/notifications/unread-count

Source: https://docs.pingcrm.xyz/api-reference

Returns the number of unread notifications for the user.

```APIDOC
## GET /api/v1/notifications/unread-count

### Description
Get the count of unread notifications.

### Method
GET

### Endpoint
/api/v1/notifications/unread-count

### Response
#### Success Response (200)
- **count** (integer) - Number of unread notifications.

#### Response Example
{
  "count": 3
}
```

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

### POST /api/v1/auth/register

Source: https://docs.pingcrm.xyz/api-reference

Registers a new user account with email and password.

```APIDOC
## POST /api/v1/auth/register

### Description
Register a new account with email and password.

### Method
POST

### Endpoint
/api/v1/auth/register

### Authentication
Not required (public endpoint).

### Request Body
- **email** (string) - Required - The email address for the new account.
- **password** (string) - Required - The password for the new account.

### Response
#### Success Response (200)
- **data** (object) - The created user object.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### GET /api/v1/notifications

Source: https://docs.pingcrm.xyz/api-reference

Retrieves a list of notifications for the authenticated user.

```APIDOC
## GET /api/v1/notifications

### Description
List notifications.

### Method
GET

### Endpoint
/api/v1/notifications

### Response
#### Success Response (200)
- **notifications** (array) - List of notification objects.

#### Response Example
{
  "notifications": []
}
```

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

### Dependency Layers Diagram

Source: https://docs.pingcrm.xyz/architecture

Shows the layered architecture of the project, from frontend down to core, with each layer's main technology or responsibility. Use this diagram to understand the overall system structure and the allowed dependency direction.

```text
┌─────────────┐  
│   Frontend  │  Next.js + React  
├─────────────┤  
│  API Layer  │  FastAPI routes (thin handlers)  
├─────────────┤  
│  Services   │  Business logic, follow-up engine, scoring  
├─────────────┤  
│Integrations │  Gmail, Telegram, Twitter, LinkedIn, Apollo  
├─────────────┤  
│   Models    │  SQLAlchemy ORM + Pydantic schemas  
├─────────────┤  
│    Core     │  Config, auth, database, Redis, logging  
└─────────────┘  
```

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

### GET /api/v1/contacts/{contact_id}/interactions

Source: https://docs.pingcrm.xyz/api-reference

Lists interactions for a contact.

```APIDOC
## GET /api/v1/contacts/{contact_id}/interactions

### Description
List interactions.

### Method
GET

### Endpoint
/api/v1/contacts/{contact_id}/interactions

### Parameters
#### Path Parameters
- **contact_id** (integer) - Required - Contact ID

### Response
#### Success Response (200)
- **interactions** (array) - List of interactions

#### Response Example
{
  "interactions": []
}
```

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

### Run application in three terminals

Source: https://docs.pingcrm.xyz/setup

Commands to run the application in three separate terminals: backend API, frontend dev server, and Celery worker with beat.

```bash
# Terminal 1 -- Backend API (http://localhost:8000)  
cd backend && source .venv/bin/activate  
uvicorn app.main:app --reload  
  
# Terminal 2 -- Frontend (http://localhost:3000)  
cd frontend && npm run dev  
  
# Terminal 3 -- Celery worker + beat  
cd backend && source .venv/bin/activate  
celery -A worker.celery_app worker --beat --loglevel=info  
```

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

### POST /api/v1/contacts/sync/whatsapp

Source: https://docs.pingcrm.xyz/api-reference

Initiates a background backfill of WhatsApp messages. Returns immediately; a notification fires when the task completes.

```APIDOC
## POST /api/v1/contacts/sync/whatsapp

### Description
Backfill WhatsApp messages.

### Method
POST

### Endpoint
/api/v1/contacts/sync/whatsapp

### Response
#### Success Response (200)
- **status** (string) - Status of sync

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

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

### GET /api/v1/telegram/sync-progress

Source: https://docs.pingcrm.xyz/api-reference

Polls the progress of a Telegram sync operation.

```APIDOC
## GET /api/v1/telegram/sync-progress

### Description
Poll Telegram sync progress.

### Method
GET

### Endpoint
/api/v1/telegram/sync-progress

### Response
#### Success Response (200)
- **progress** (integer) - Progress percentage

#### Response Example
{
  "progress": 50
}
```

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

### GET /api/v1/contacts/{contact_id}

Source: https://docs.pingcrm.xyz/api-reference

Retrieves a single contact by its ID.

```APIDOC
## GET /api/v1/contacts/{contact_id}

### Description
Get a contact.

### Method
GET

### Endpoint
/api/v1/contacts/{contact_id}

### Parameters
#### Path Parameters
- **contact_id** (integer) - Required - Contact ID

### Response
#### Success Response (200)
- **id** (integer) - Contact ID
- **name** (string) - Contact name
- **email** (string) - Contact email

#### Response Example
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}
```

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

### Backend directory structure

Source: https://docs.pingcrm.xyz/architecture

Directory tree of the FastAPI backend under backend/app/, showing the layered structure: main.py, api/ route handlers, models/, schemas/, services/, integrations/, and core/.

```text
backend/app/  
├── main.py              # FastAPI app factory, CORS, router mounting  
├── api/                 # Route handlers (REST endpoints)  
│   ├── contacts_routes/ # Contacts: CRUD, imports, sync, taxonomy, messaging  
│   ├── interactions.py  # Interaction timeline  
│   ├── suggestions.py   # Follow-up suggestions, snooze, dismiss  
│   ├── identity.py      # Identity resolution scan, review, merge  
│   ├── organizations.py # Company records and stats  
│   ├── notifications.py # In-app notification feed  
│   ├── auth.py          # Login, register, OAuth callbacks  
│   ├── telegram.py      # Connect, sync, send messages  
│   ├── twitter.py       # OAuth PKCE flow, polling  
│   ├── linkedin.py      # Extension data push (profiles + messages)  
│   ├── extension.py     # Chrome extension pairing  
│   ├── activity.py      # Recent activity feed  
│   └── settings.py      # User preferences  
├── models/              # SQLAlchemy 2.x async ORM models  
├── schemas/             # Pydantic request/response schemas  
├── services/            # Business logic layer  
├── integrations/        # Third-party API clients  
└── core/                # Config, auth, database, encryption, Redis  
```

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

### GET /api/v1/auth/whatsapp/status

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the current status of the WhatsApp session.

```APIDOC
## GET /api/v1/auth/whatsapp/status

### Description
Get the WhatsApp session status.

### Method
GET

### Endpoint
/api/v1/auth/whatsapp/status

### Authentication
Bearer token required.

### Response
#### Success Response (200)
- **data** (object) - Contains session status.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### PUT /api/v1/settings/sync

Source: https://docs.pingcrm.xyz/api-reference

Updates the sync schedule preferences.

```APIDOC
## PUT /api/v1/settings/sync

### Description
Update sync schedule preferences.

### Method
PUT

### Endpoint
/api/v1/settings/sync

### Parameters
#### Request Body
- **frequency** (string) - Required - Sync frequency (e.g., daily, weekly).
- **time** (string) - Required - Time of day for sync (e.g., "02:00").

### Request Example
{
  "frequency": "daily",
  "time": "02:00"
}

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

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

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

### GET /api/v1/auth/me

Source: https://docs.pingcrm.xyz/api-reference

Retrieves the profile of the currently authenticated user.

```APIDOC
## GET /api/v1/auth/me

### Description
Get the current authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/me

### Authentication
Bearer token required.

### Response
#### Success Response (200)
- **data** (object) - The current user object.
- **error** (null) - Always null on success.
- **meta** (object) - Additional metadata.

#### Response Example
{
  "data": {},
  "error": null,
  "meta": {}
}
```

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

### GET /api/v1/extension/pair

Source: https://docs.pingcrm.xyz/api-reference

Unauthenticated endpoint used by the extension to poll for a token.

```APIDOC
## GET /api/v1/extension/pair

### Description
Poll for token (unauthenticated, used by extension).

### Method
GET

### Endpoint
/api/v1/extension/pair
```

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

### GET /api/v1/sync-history/stats

Source: https://docs.pingcrm.xyz/api-reference

Retrieves aggregate sync statistics grouped by platform.

```APIDOC
## GET /api/v1/sync-history/stats

### Description
Get aggregate sync statistics per platform.

### Method
GET

### Endpoint
/api/v1/sync-history/stats

### Response
#### Success Response (200)
- **stats** (object) - Aggregate statistics per platform.

#### Response Example
{
  "stats": {
    "platform1": {
      "totalRecords": 100
    }
  }
}
```

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

### GET /api/v1/contacts/tags

Source: https://docs.pingcrm.xyz/api-reference

Returns a flat list of tags currently in use.

```APIDOC
## GET /api/v1/contacts/tags

### Description
Flat list of in-use tags.

### Method
GET

### Endpoint
/api/v1/contacts/tags

### Response
#### Success Response (200)
- **tags** (array) - List of tags

#### Response Example
{
  "tags": []
}
```

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

### GET /api/v1/contacts/ids

Source: https://docs.pingcrm.xyz/api-reference

Returns a list of contact IDs for bulk operations.

```APIDOC
## GET /api/v1/contacts/ids

### Description
Bulk contact IDs for select-all functionality.

### Method
GET

### Endpoint
/api/v1/contacts/ids

### Response
#### Success Response (200)
- **ids** (array) - List of contact IDs

#### Response Example
{
  "ids": [1, 2, 3]
}
```

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

### POST /api/v1/contacts/tags/apply

Source: https://docs.pingcrm.xyz/api-reference

Applies a taxonomy to contacts.

```APIDOC
## POST /api/v1/contacts/tags/apply

### Description
Apply taxonomy to contacts.

### Method
POST

### Endpoint
/api/v1/contacts/tags/apply

### Parameters
#### Request Body
- **taxonomy** (object) - Required - Taxonomy to apply

### Request Example
{
  "taxonomy": {}
}

### Response
#### Success Response (200)
- **status** (string) - Status of application

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

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

### Pin backend and frontend image versions in docker-compose.prod.yml

Source: https://docs.pingcrm.xyz/operations/updates

Overrides the default :latest tag to pin exact image versions for the backend and frontend services in docker-compose.prod.yml.

```yaml
services:  
  backend:  
    image: ghcr.io/sneg55/pingcrm/backend:1.7.0  
  frontend:  
    image: ghcr.io/sneg55/pingcrm/frontend:1.7.0  
```

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

### GET /api/v1/contacts

Source: https://docs.pingcrm.xyz/api-reference

Lists contacts with pagination, search, and filtering capabilities.

```APIDOC
## GET /api/v1/contacts

### Description
List contacts with pagination, search, and filtering.

### Method
GET

### Endpoint
/api/v1/contacts

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination
- **search** (string) - Optional - Search query
- **filter** (string) - Optional - Filter criteria

### Response
#### Success Response (200)
- **data** (array) - List of contacts
- **meta** (object) - Pagination metadata

#### Response Example
{
  "data": [],
  "meta": {}
}
```