Planfix REST API Client

Toolkit for working with Planfix REST API for AI agents.

📋 Description

Library and CLI utilities for working with Planfix REST API. Designed for use by AI agents to update tasks in local documentation and Planfix.

✨ Features

Task Management - Full CRUD operations for tasks (create, read, update, list)
Comment Management - Complete comment operations with HTML formatting support
Data Tags - Full support for data tags and data tag entries (used for worklog, analytics, etc.)
Contact & Project Management - Read operations for contacts and projects
Worklog (Time Tracking) - Simplified worklog entry creation with automatic field detection
Directories - Reference data management with automatic caching
Caching - Automatic caching for reference data (directories, work types) with configurable TTL
Search Functionality - Search tasks, contacts, and projects with filters
CLI Utilities - Command-line tools for all major operations
Type Safety - Full type hints and Pydantic models
Comprehensive Logging - Built-in request/response logging
HTML Formatting - Support for rich text formatting in descriptions and comments
Silent Mode - Update operations without notifications
Modular Architecture - Decomposed into separate API modules for better maintainability

📋 Requirements

Python 3.10 or higher
Planfix account with REST API access (paid or premium account required)

📦 Installation

From Source

Clone the repository:

git clone https://github.com/LabutinPA/planfix-rest-api.git
cd planfix-rest-api

Install dependencies:

# Using pip
pip install -r requirements.txt

# Or using virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Install as Package

pip install -e .

🚀 Quick Start

Configuration

Copy config.sample.json to config.json:

# Windows
copy config.sample.json config.json

# Linux/Mac
cp config.sample.json config.json

Edit config.json and specify your API token:

{
  "api_url": "https://your-account.planfix.com/rest",
  "api_token": "your_token_here",
  "account": "your-account"
}

🏗️ Architecture

The client is decomposed into separate API modules for better maintainability:

base.py - Base HTTP client with request handling and logging
cache.py - Caching utilities for reference data
tasks.py - Tasks API
comments.py - Comments API
contacts.py - Contacts API
projects.py - Projects API
datatags.py - Data Tags API
directories.py - Directories API (with caching)
worklog.py - Worklog API (with caching)
client.py - Main client that composes all API modules

CLI utilities are located in the planfix_cli/ package:

planfix_cli/tasks.py - Task management CLI
planfix_cli/comments.py - Comment management CLI
planfix_cli/contacts.py - Contact management CLI
planfix_cli/projects.py - Project management CLI
planfix_cli/search.py - Search CLI

Usage Example

from planfix import PlanfixClient, load_config

config = load_config()
client = PlanfixClient(config)

# New API structure (after decomposition)
task = client.tasks.get_task(12345)
tasks = client.tasks.get_tasks(page_size=10)

comment = client.comments.add_task_comment(12345, "Comment text")
comments = client.comments.get_task_comments(12345)

contact = client.contacts.get_contact(11111)
contacts = client.contacts.get_contacts()

project = client.projects.get_project(1470)
projects = client.projects.get_projects()

# Worklog with automatic caching
work_types = client.worklog.get_work_types_from_worklog()  # Cached!
worklog_entry = client.worklog.create_worklog_entry(
    task_id=12345,
    date="27-01-2025",
    start_time="10:00",
    end_time="12:00"
)

# Directories with automatic caching
entries = client.directories.get_directory_entries(directory_id=10)  # Cached!
entry = client.directories.get_directory_entry(directory_id=10, entry_key=1)  # Cached!

Caching

Reference data (directories, work types) is automatically cached for 1 hour (configurable). Cache is in-memory and lives only during the program execution.

See Caching Documentation for details.

📚 Documentation

Getting Started

Developer Guide - Start here! Understanding PlanFix structure and concepts
AI agent usage documentation - usage examples for automation

PlanFix Semantics

PlanFix API Semantics - Detailed semantics documentation

Help Center Research

Help Center Research - NEW! Comprehensive research from PlanFix help center
Comprehensive Documentation from Help Center - Overview of all categories
Semantics from Help Center - Detailed semantics information
REST API from Help Center - REST API information
Detailed Analysis from Help Center - Detailed analysis of high-relevance pages

Research & Development

Data Tags in Comments - Solution - Complete solution for retrieving data tags in comments
Usage Examples - Practical examples for common API usage scenarios

API Reference

📚 See full documentation index

Main references:

API Reference - main REST API reference
REST API Complete Reference - quick reference for comment endpoints with dataTags
API Documentation Enriched - complete documentation (22,874 lines, used as data source)
API Coverage Status - implementation status of all API endpoints in the client

Testing

Test documentation

🛠️ CLI Utilities

Main CLI Tools

CLI tools are available as command-line scripts after installation:

planfix-tasks - task management (CRUD)
planfix-comments - comment management (CRUD)
planfix-contacts - contact management (read-only, API limitation)
planfix-projects - project management (read-only, client limitation - API supports create/update)
planfix-search - information search

Alternatively, you can run them as Python modules:

python -m planfix_cli.tasks
python -m planfix_cli.comments
python -m planfix_cli.contacts
python -m planfix_cli.projects
python -m planfix_cli.search

Development Tools

scripts/crawl_help_center.py - Crawler for PlanFix help center (extracts semantics, REST API docs)
scripts/extract_complete_api_docs.py - Extract complete API documentation from Swagger JSON (extracts all endpoints, parameters, fields, examples from https://help.planfix.com/restapidocs/)

Usage Examples

Task Management

# Get task by ID
planfix-tasks get 12345
# Or: python -m planfix_cli.tasks get 12345

# Create new task
planfix-tasks create --name "New task" --description "Description"

# Update task
planfix-tasks update 12345 --name "Updated title" --silent

# Get task list
planfix-tasks list --offset 0 --page-size 50

Comment Management

# Get task comments
planfix-comments list 12345
# Or: python -m planfix_cli.comments list 12345

# Add comment
planfix-comments add 12345 "Comment text"

# Update comment
planfix-comments update 12345 67890 "Updated text"

# Delete comment
planfix-comments delete 67890

Contact Management

# Get contact by ID
planfix-contacts get 12345
# Or: python -m planfix_cli.contacts get 12345

# Get contact list
planfix-contacts list --page-size 50

Project Management

# Get project by ID
planfix-projects get 12345
# Or: python -m planfix_cli.projects get 12345

# Get project list
planfix-projects list

Search

# Search tasks
planfix-search tasks --name "Task name"
# Or: python -m planfix_cli.search tasks --name "Task name"

# Search contacts
planfix-search contacts --name "Contact name"

# Search projects
planfix-search projects --name "Project name"

📦 Library Usage

Basic Example

from planfix import PlanfixClient, load_config

# Load configuration
config = load_config('config.json')

# Create client
client = PlanfixClient(config)

# Get task
task = client.get_task(12345)
print(f"Task: {task.name}")

Advanced Examples

# Create task with HTML formatting
task = client.create_task({
    'name': 'New task',
    'description': '<p><strong>Important</strong> task description</p>',
    'project': {'id': 12345}
})

# Update task silently (without notifications)
client.update_task(12345, {
    'name': 'Updated title',
    'description': 'Updated description'
}, silent=True)

# Get tasks with filters
tasks = client.get_tasks(
    offset=0,
    page_size=50,
    filters=[
        {
            'type': 1,
            'operator': 'equal',
            'value': 'search term'
        }
    ]
)

# Add comment with HTML
comment = client.add_task_comment(
    12345,
    '<p>Comment with <strong>formatting</strong></p>'
)

See AI agent usage documentation for more examples.

🧪 Testing

See Test Coverage for detailed test coverage information.

Quick Basic Tests

python tests/test_integration.py

Full Testing with pytest

# All integration tests
pytest tests/ -v -m integration

# Cache tests
pytest tests/test_cache.py -v

# Specific test
pytest tests/test_integration.py::test_get_task -v -m integration

Test Project

All tests use project ID 1470 ("MCP Server Tests") as a sandbox for testing.

Environment Variables for Tests

For full testing, set (optional):

Windows PowerShell:

$env:PLANFIX_TEST_TASK_ID = "12345"
$env:PLANFIX_TEST_PROJECT_ID = "1470"  # Optional, 1470 is default
$env:PLANFIX_TEST_CONTACT_ID = "11111"

Linux/Mac:

export PLANFIX_TEST_TASK_ID=12345
export PLANFIX_TEST_PROJECT_ID=1470  # Optional, 1470 is default
export PLANFIX_TEST_CONTACT_ID=11111

For more details: tests/README.md

📊 API Coverage

This client implements a subset of Planfix REST API endpoints. For a complete list of all API endpoints and their implementation status, see API Coverage Status.

Quick Summary:

✅ 23 endpoints fully implemented (Tasks, Comments, Contacts, Projects, Data Tags, Directories, Worklog)
🟡 3 endpoints partially implemented (Task checklist, Projects/Contacts - read-only)
❌ 80 endpoints not yet implemented

Implemented Features:

Task CRUD operations (create, read, update, list)
Comment CRUD operations (create, read, update, delete)
Contact read operations (get, list)
Project read operations (get, list)
Task checklist (read)
Search functionality (via filters)
Data tags (full CRUD support)

Not Yet Implemented:

File operations (upload, download, attach)
Project/Contact create/update
Custom fields management
Reports, Processes, Directories
Users/Employees operations

See API Coverage Status for detailed implementation status of all 106 API endpoints.

🔗 Links

🙏 Acknowledgments

This project was developed collaboratively by Pavel Labutin (labutinpa@gmail.com) and Composer, an AI coding assistant powered by Cursor.

Pavel Labutin contributed to:

Architecture and design decisions
Project management and coordination
Bug fixing and debugging
Documentation research and analysis

Composer contributed to:

Code implementation and development
Code refactoring and improvements
HTML formatting support analysis and implementation
Documentation updates and improvements
Type checking enhancements (strict Python mode)
Code review and quality improvements
Error handling refinements

Together we did a great job! 🎉

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📝 Changelog

See CHANGELOG.md for a list of changes and version history.

🤝 Contributing

Contributions are welcome! We appreciate your help in improving this project.

How to Contribute

Fork the repository and clone your fork
Create a branch for your feature or bugfix:
```
git checkout -b feature/your-feature-name
```
Make your changes following the project's code style:
- Use type hints for all functions
- Follow PEP 8 style guide
- Add docstrings to new functions/classes
- Write tests for new functionality
Run tests to ensure everything works:
```
pytest tests/ -v
```
Commit your changes with clear commit messages
Push to your fork and create a Pull Request

Development Setup

# Clone repository
git clone https://github.com/LabutinPA/planfix-rest-api.git
cd planfix-rest-api

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Run tests
pytest tests/ -v

Code Style

Follow PEP 8 style guide
Use type hints for all functions and methods
Format code with black (already configured)
Write clear docstrings for public APIs

Reporting Issues

If you find a bug or have a feature request, please open an issue on GitHub with:

Clear description of the problem/feature
Steps to reproduce (for bugs)
Expected vs actual behavior
Python version and environment details

☮︎

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
docs		docs
planfix		planfix
planfix_cli		planfix_cli
scripts		scripts
tests		tests
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
config.sample.json		config.sample.json
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt

License

LabutinPA/planfix-rest-api

Folders and files

Latest commit

History

Repository files navigation