# Linkit

> Linkit is e-commerce integration middleware. It connects delivery platforms, marketplaces, and AI services through a single REST API, letting you manage products, inventory, orders, and integrations from one place.

Linkit is built on PocketBase and bundles a Go backend, SvelteKit admin dashboard, SvelteKit landing page, and Next.js documentation site into a single Linux binary.

## API

Base URL: `https://linkit.works/api/v1`

Authentication: Bearer token or API key in the `Authorization` header.

### Core Resources

- **Branches**: Physical stores or locations. Creating a branch auto-generates one SKU per existing product.
- **Brands**: Brand management with product associations and bulk operations.
- **Categories**: Hierarchical product categorization with unlimited nesting depth. Tree view and move operations.
- **Customer Addresses**: Customer delivery and billing addresses.
- **Customer Groups**: Customer segmentation for pricing tiers and access control.
- **Customers**: Customer profiles with addresses, groups, search, and lookup by email or phone.
- **Generics**: Generic medicine names for pharmaceutical catalogs.
- **Integrations**: Connect external platforms (Salla, HungerStation, Jahez, Noon Now, Keeta, Trendyol, etc.) and sync data on demand or on schedule.
- **Offers**: Promotion engine for direct discounts, package deals, bundle deals, BOGO/BTGO, and buy-X-get-discount scenarios with iv_id/barcode targeting.
- **Orders**: Unified order ingestion from any source. Status tracking, analytics, export, and bulk operations.
- **Products**: Central product catalog with bilingual names (English/Arabic), pricing, VAT, barcodes, and brand/category assignments. CRUD + bulk upsert up to 1,000 records.
- **SKUs**: Per-branch inventory records (product × branch). Manage stock levels, pricing, and availability.
- **Tags**: Tagging system for flexible product classification.

### Pagination

All list endpoints return paginated results with `page`, `limit`, `sort` query parameters. Default: page=1, limit=20, max=100. Prefix sort field with `-` for descending.

### Bulk Operations

Most resources support bulk create/update/upsert with up to 1,000 records per request via `/bulk` endpoints.

### Error Format

```json
{"code": 400, "error": "Validation failed", "details": {"field": "name_en", "message": "Name is required"}}
```

## Endpoints

### Branches

- `GET /api/v1/branches` — List branches
- `POST /api/v1/branches` — Create new branch
- `POST /api/v1/branches/bulk` — Bulk branch operations
- `GET /api/v1/branches/{ivId}` — Get branch by ID
- `PUT /api/v1/branches/{ivId}` — Update branch
- `DELETE /api/v1/branches/{ivId}` — Delete branch

### Brands

- `GET /api/v1/brands` — List brands
- `POST /api/v1/brands` — Create new brand
- `POST /api/v1/brands/bulk` — Bulk brand operations
- `GET /api/v1/brands/code/{brandCode}` — Get brand by code
- `PUT /api/v1/brands/code/{brandCode}` — Update brand
- `DELETE /api/v1/brands/code/{brandCode}` — Delete brand
- `PATCH /api/v1/brands/code/{brandCode}/products` — Update brand products

### Categories

- `GET /api/v1/categories` — List categories
- `POST /api/v1/categories` — Create new category
- `GET /api/v1/categories/code/{code}` — Get category by code
- `PUT /api/v1/categories/code/{code}` — Update category
- `DELETE /api/v1/categories/code/{code}` — Delete category
- `PATCH /api/v1/categories/code/{code}/move` — Move category
- `PATCH /api/v1/categories/code/{code}/products` — Update category products
- `GET /api/v1/categories/tree` — Get category tree

### Connectivity

- `GET /api/v1/ping` — Ping endpoint

### Customer Addresses

- `GET /api/v1/customers/{customerId}/addresses` — List all addresses for a customer
- `POST /api/v1/customers/{customerId}/addresses` — Add a new address to customer
- `PUT /api/v1/customers/{customerId}/addresses/{addressId}` — Update an existing address
- `DELETE /api/v1/customers/{customerId}/addresses/{addressId}` — Delete a customer address

### Customer Groups

- `GET /api/v1/customer-groups` — List all customer groups
- `POST /api/v1/customer-groups` — Create a new customer group
- `PUT /api/v1/customer-groups/{id}` — Update customer group details
- `DELETE /api/v1/customer-groups/{id}` — Delete a customer group

### Customers

- `GET /api/v1/customers` — List customers with pagination and filtering
- `POST /api/v1/customers` — Create a new customer
- `GET /api/v1/customers/lookup` — Lookup customer by email or phone
- `POST /api/v1/customers/search` — Advanced customer search
- `GET /api/v1/customers/{id}` — Get customer by ID
- `PUT /api/v1/customers/{id}` — Update customer details
- `DELETE /api/v1/customers/{id}` — Delete customer and all associated data

### Documentation

- `GET /api/v1/docs` — Swagger UI
- `GET /api/v1/docs/info` — API documentation info
- `GET /api/v1/docs/swagger.json` — Get Swagger specification

### Generics

- `GET /api/v1/generics` — List generic medicines
- `POST /api/v1/generics` — Create new generic medicine
- `POST /api/v1/generics/bulk` — Bulk generic operations
- `POST /api/v1/generics/cache/clear` — Clear generic cache
- `GET /api/v1/generics/code/{genericCode}` — Get generic medicine by code
- `PUT /api/v1/generics/code/{genericCode}` — Update generic medicine
- `DELETE /api/v1/generics/code/{genericCode}` — Delete generic medicine
- `POST /api/v1/generics/search` — Search generic medicines

### Health

- `GET /api/v1/health` — Health check
- `GET /api/v1/health/system` — System health check

### Integrations

- `GET /api/v1/apps` — List apps
- `GET /api/v1/integrations` — List apps
- `POST /api/v1/integrations/{orgId}/execute-batch` — Execute multiple integrations
- `GET /api/v1/integrations/{orgId}/{slug}/config` — Get integration config
- `POST /api/v1/integrations/{orgId}/{slug}/execute` — Execute integration

### Metrics

- `GET /api/v1/telemetry` — System telemetry

### Offers

- `GET /api/v1/offers` — List offers
- `POST /api/v1/offers` — Create offer
- `POST /api/v1/offers/bulk` — Bulk upsert offers
- `GET /api/v1/offers/{id}` — Get offer
- `PUT /api/v1/offers/{id}` — Update offer
- `DELETE /api/v1/offers/{id}` — Delete offer
- `PATCH /api/v1/offers/{id}/status` — Update offer status
- `GET /api/v1/reports/offers` — Offers analytics report

### Orders

- `GET /api/v1/orders` — List orders
- `POST /api/v1/orders` — Create order
- `GET /api/v1/orders/analytics/summary` — Get order analytics
- `POST /api/v1/orders/bulk` — Bulk create orders
- `DELETE /api/v1/orders/bulk` — Bulk delete orders
- `PATCH /api/v1/orders/bulk/status` — Bulk update order status
- `GET /api/v1/orders/export` — Export orders
- `GET /api/v1/orders/{id}` — Get order by ID
- `PUT /api/v1/orders/{id}` — Update order
- `DELETE /api/v1/orders/{id}` — Delete order
- `PATCH /api/v1/orders/{id}/status` — Update order status

### Organization Apps

- `GET /api/v1/org-apps/{orgAppId}/dependents` — Preview dependents for an organization app
- `DELETE /api/v1/org-apps/{orgAppId}/uninstall` — Uninstall an organization app

### Posts

- `GET /api/v1/posts` — List Published posts
- `GET /api/v1/posts/id/{id}` — Get post by ID
- `GET /api/v1/posts/{slug}` — Get post by slug

### Products

- `GET /api/v1/products` — List products with pagination and filtering
- `POST /api/v1/products` — Create a new product
- `POST /api/v1/products/bulk` — Bulk product operations
- `POST /api/v1/products/fix-skus` — Fix missing SKUs for all products
- `GET /api/v1/products/iv/{ivId}` — Get product by Internal Vendor ID or internal ID
- `PUT /api/v1/products/iv/{ivId}` — Update product by Internal Vendor ID
- `DELETE /api/v1/products/iv/{ivId}` — Delete product and all related data

### SKUs

- `POST /api/v1/skus` — Create new SKU with organization scoping
- `POST /api/v1/skus/bulk` — Bulk SKU operations
- `GET /api/v1/skus/iv/{ivId}` — Get SKU by IV ID or internal ID
- `PUT /api/v1/skus/iv/{ivId}` — Update SKU
- `DELETE /api/v1/skus/iv/{ivId}` — Delete SKU
- `PATCH /api/v1/skus/iv/{ivId}/stock` — Update SKU stock

### Tags

- `GET /api/v1/tags` — List all tags

### Verifications

- `POST /api/v1/verifications/{slug}` — Verify app credentials

## MCP Integration

Linkit exposes a Model Context Protocol (MCP) server at `/api/v1/mcp` (also `/mcp`). AI assistants (Claude, Cursor, Windsurf, Gemini) can connect to discover and call all API operations as semantic tools.

MCP client config:
```json
{"mcpServers": {"linkit": {"url": "https://linkit.works/api/v1/mcp"}}}
```

### Semantic MCP Tools

| Tool | Description |
|------|-------------|
| check_health | Check system health — ping, health check, system info, and telemetry metrics. |
| manage_branches | Manage branches (stores/locations) — list, get, create, update, delete, and bulk upsert. |
| manage_catalog | Manage catalog metadata — categories (with tree/move), brands, tags, and generic records. |
| manage_content | Access content — blog posts, API documentation, swagger spec, and verification endpoints. |
| manage_customers | Manage customers — CRUD, search, lookup, customer groups, and customer addresses. |
| manage_integrations | Manage integrations and apps — list apps, view configs, execute syncs, batch execute, and manage org apps. |
| manage_inventory | Manage SKU-level inventory — list, get, create, update, delete, bulk upsert, and adjust stock levels. |
| manage_offers | Manage offers and promotions — list, get, create, update, delete, bulk upsert, and status operations. |
| manage_orders | Manage orders — list, get, create, update, delete, bulk operations, status changes, analytics, and export. |
| manage_products | Manage products in the Linkit catalog — list, get, create, update, delete, bulk upsert, and fix SKUs. |
| linkit_api | Generic fallback for any API endpoint |

Each tool takes an `action` parameter to select the specific operation.

### MCP Resources

- `linkit://docs/swagger.json` — Full OpenAPI 2.0 specification (JSON)
- `linkit://docs/swagger.yaml` — Full OpenAPI 2.0 specification (YAML)
- `linkit://docs/api-overview` — API overview with auth, pagination, resources
- `linkit://docs/tool-catalog` — Complete tool + action catalog

## Plugins

Official plugins for e-commerce platforms:

- **WooCommerce** — WordPress plugin for syncing products, inventory, and orders
- **OpenCart 3** — Module for OpenCart 3.x integration
- **OpenCart 4** — Module for OpenCart 4.x integration
- **Odoo** — Odoo module for ERP integration (inventory, products)
- **Odoo POS** — Odoo Point of Sale module for order synchronization

## Documentation

- [API Overview](https://linkit.works/docs/guide/api/overview/)
- [Authentication](https://linkit.works/docs/guide/api/authentication/)
- [Products API](https://linkit.works/docs/guide/api/products/)
- [Branches API](https://linkit.works/docs/guide/api/branches/)
- [SKUs API](https://linkit.works/docs/guide/api/skus/)
- [Orders API](https://linkit.works/docs/guide/api/orders/)
- [Offers API](https://linkit.works/docs/guide/api/offers/)
- [Categories API](https://linkit.works/docs/guide/api/categories/)
- [Brands API](https://linkit.works/docs/guide/api/brands/)
- [Customers API](https://linkit.works/docs/guide/api/customers/)
- [Generics API](https://linkit.works/docs/guide/api/generics/)
- [Integrations API](https://linkit.works/docs/guide/api/integrations/)
- [Health & Telemetry](https://linkit.works/docs/guide/api/health/)
- [Bulk Operations](https://linkit.works/docs/guide/api/bulk-operations/)
- [MCP Integration](https://linkit.works/docs/guide/api/mcp/)
- [Plugin Guides](https://linkit.works/docs/guide/plugins/)
- [Swagger JSON](https://linkit.works/swagger.json)
- [Swagger YAML](https://linkit.works/swagger.yaml)