Kwork API Client

Unofficial Python client for Kwork.ru API.

Features

• ✅ Full API coverage (all endpoints from HAR dump analysis)
• ✅ Async/await support
• ✅ Pydantic models for type safety
• ✅ Clear error handling
• ✅ Session management with cookies + tokens
• ✅ JSON structured logging support
• ✅ Comprehensive test suite (unit + integration)

Installation

# With pip
pip install kwork-api

# With uv
uv pip install kwork-api

# From source
git clone http://5.188.26.192:3000/claw/kwork-api.git
cd kwork-api
uv pip install -e ".[dev]"

Quick Start

Authentication

from kwork_api import KworkClient

# Login with credentials
client = await KworkClient.login("username", "password")

# Or restore from token
client = KworkClient(token="your_web_auth_token")

# Use context manager for automatic cleanup
async with KworkClient(token="token") as client:
    # Make requests
    pass

Catalog

# Get catalog list
catalog = await client.catalog.get_list(page=1)
for kwork in catalog.kworks:
    print(f"{kwork.title}: {kwork.price} RUB")

# Get kwork details
details = await client.catalog.get_details(kwork_id=123)
print(details.full_description)

Projects

# Get projects list
projects = await client.projects.get_list(page=1)

# Get orders where user is customer
customer_orders = await client.projects.get_payer_orders()

# Get orders where user is performer
performer_orders = await client.projects.get_worker_orders()

User

# Get user info
user_info = await client.user.get_info()

# Get reviews
reviews = await client.user.get_reviews(page=1)

# Get favorite kworks
favorites = await client.user.get_favorite_kworks()

Reference Data

# Get cities
cities = await client.reference.get_cities()

# Get countries
countries = await client.reference.get_countries()

# Get timezones
timezones = await client.reference.get_timezones()

# Get features
features = await client.reference.get_features()

Notifications

# Get notifications
notifications = await client.notifications.get_list()

# Fetch new notifications
new_notifications = await client.notifications.fetch()

# Get dialogs
dialogs = await client.notifications.get_dialogs()

Error Handling

from kwork_api import KworkAuthError, KworkApiError, KworkNotFoundError

try:
    catalog = await client.catalog.get_list()
except KworkAuthError as e:
    print(f"Auth failed: {e}")
except KworkNotFoundError as e:
    print(f"Not found: {e}")
except KworkApiError as e:
    print(f"API error [{e.status_code}]: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Rate Limiting

Rate limiting is not implemented in the library. Handle it in your code:

import asyncio

for page in range(1, 10):
    catalog = await client.catalog.get_list(page=page)
    await asyncio.sleep(1)  # 1 second delay between requests

Logging

The library uses standard logging module. For JSON logging (Kibana-compatible):

import logging
import structlog
import json

# Configure structlog for JSON output
structlog.configure(
    processors=[
        structlog.processors.JSONRenderer()
    ],
    wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
)

# Use in your code
logger = structlog.get_logger()
logger.info("kwork_request", endpoint="/catalogMainv2", page=1)

Testing

Unit Tests (mocks)

# Run unit tests only
pytest tests/unit/ -m unit

# With coverage
pytest tests/unit/ -m unit --cov=kwork_api

Integration Tests (real API)

# Set credentials
export KWORK_USERNAME=your_username
export KWORK_PASSWORD=your_password

# Run integration tests
pytest tests/integration/ -m integration

# Skip integration tests in CI
pytest tests/ -m "not integration"

Available Endpoints

Catalog

• GET /catalogMainv2 — Catalog list with pagination
• POST /getKworkDetails — Kwork details
• POST /getKworkDetailsExtra — Extra kwork details

Projects

• POST /projects — Projects list
• POST /payerOrders — Customer orders
• POST /workerOrders — Performer orders

User

• POST /user — User info
• POST /userReviews — User reviews
• POST /favoriteKworks — Favorite kworks
• POST /favoriteCategories — Favorite categories

Reference Data

• POST /cities — Cities list
• POST /countries — Countries list
• POST /timezones — Timezones list
• POST /getAvailableFeatures — Available features
• POST /getPublicFeatures — Public features
• POST /getBadgesInfo — Badges info

Notifications

• POST /notifications — Notifications list
• POST /notificationsFetch — Fetch new notifications
• POST /dialogs — Dialogs list
• POST /blockedDialogList — Blocked dialogs

Other

• POST /myWants — User wants
• POST /wantsStatusList — Wants status
• POST /kworksStatusList — Kworks status
• POST /offers — Offers
• POST /exchangeInfo — Exchange info
• POST /getChannel — Channel info
• POST /getInAppNotification — In-app notification
• POST /getSecurityUserData — Security user data
• POST /isDialogAllow — Check dialog permission
• POST /viewedCatalogKworks — Viewed kworks
• POST /updateSettings — Update settings
• POST /offline — Set offline status
• POST /actor — Actor info

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run linter
ruff check src/ tests/

# Format code
ruff format src/ tests/

# Run all tests
pytest

# Build package
uv build

License

MIT License

Disclaimer

This is an unofficial client. Kwork.ru is not affiliated with this project. Use at your own risk and respect Kwork's terms of service.

CI Test

CI Test

Testing Gitea Actions workflow.