# uCoz API (uAPI) — Full Reference

> REST API for full management of websites hosted on the uCoz platform. Provides programmatic access to all site modules: content, users, e-commerce, design, templates, and tools. Suitable for automation, integrations, and AI agents.

Documentation: https://api.ucoz.net/

## Authentication

All requests require a Bearer JWT token:

```
Authorization: Bearer <token>
```

Tokens are created in the site control panel under **Site → uAPI**. The token is passed in the header of every request.

## Base URL

The API runs on the domain of the specific site:

```
https://{yoursite}/uapi
```

Example: `https://mysite.ucoz.ru/uapi`

All paths below are relative to this base URL.

> **For AI agents**: the [uCoz MCP server](https://api.ucoz.net/mcp.html) (`npx ucoz-mcp@latest`) is recommended over direct HTTP requests — it covers templates, menus, forms, and FTP out of the box.

---

## Model Context Protocol (MCP)

Documentation: https://api.ucoz.net/mcp.html

The uCoz MCP server is the recommended integration method for AI agents. It provides direct access to templates, menus, global blocks, mail forms, and FTP through natural language commands — no manual HTTP requests needed.

**Status:** alpha. Requires Node.js 20+.

### Setup

```json
{
  "mcpServers": {
    "ucoz-mcp": {
      "command": "npx",
      "args": ["-y", "ucoz-mcp@latest"],
      "env": {
        "UCOZ_API_TOKEN": "YOUR_UCOZ_API_TOKEN",
        "UCOZ_SITE_URL":  "https://your-site.ucoz.net/",
        "UCOZ_FTP_HOST":  "your-site.ucoz.net",
        "UCOZ_FTP_USER":  "your-ftp-login",
        "UCOZ_FTP_PASS":  "your-ftp-password"
      }
    }
  }
}
```

Add this config to:
- **Cursor**: Settings → MCP → Add new MCP server
- **Claude Desktop** (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop** (Windows): `%APPDATA%/Claude/claude_desktop_config.json`
- **Codex**: Settings → MCP → type STDIO, command `npx`, args `-y ucoz-mcp@latest`

**Token**: create in site control panel → Site → uAPI.
**FTP credentials**: site control panel → FTP (activation may take up to 15 minutes).

### Tool: `templates_tool`

Manages templates, global blocks, menus, and mail forms. All template updates automatically create a backup first.

| Action | Description | Required params |
|---|---|---|
| `list_modules` | Returns the list of modules and template IDs | — |
| `get_variables` | Shows available variables for a module/template | `module_id`, `template_id` |
| `read_template` | Returns the current HTML of a template | `module_id`, `template_id` |
| `update_template` | Saves template changes (auto-backup before save) | `module_id`, `template_id`, `html_content` |
| `validate_template` | Validates HTML without saving | `module_id`, `template_id`, `content` |
| `list_backups` | Lists existing backups for a template | `module_id`, `template_id` |
| `create_backup` | Creates a manual backup | `module_id`, `template_id` |
| `delete_backup` | Deletes a backup by ID | `backup_id` |
| `restore_backup` | Restores a template from a backup | `backup_id` |
| `gblock_create` | Creates a global HTML block | `name`, `content` |
| `gblock_delete` | Deletes a global block | `block_id` |
| `menu_list` | Lists all site menus | — |
| `menu_create` | Creates a menu (`layout`: 0=horizontal, 1=vertical) | `title`, `layout` |
| `menu_get` | Returns a menu with its items | `menu_id` |
| `menu_update` | Updates menu title and/or layout | `menu_id` |
| `menu_delete` | Deletes a menu | `menu_id` |
| `menu_update_items` | Replaces menu item tree (supports `children`) | `menu_id`, `items` |
| `mail_list_forms` | Lists all mail forms | — |
| `mail_get_form` | Returns form details | `form_id` |
| `mail_create_form` | Creates a new form | `name`, `email` |
| `mail_update_form` | Updates form name, recipients, success message | `form_id` |
| `mail_delete_form` | Deletes a form | `form_id` |
| `mail_list_fields` | Lists form fields | `form_id` |
| `mail_add_field` | Adds a field (types 1–8) | `form_id`, `label`, `type` |
| `mail_update_field` | Updates a field | `form_id`, `field_id` |
| `mail_delete_field` | Deletes a field | `form_id`, `field_id` |
| `mail_move_field` | Moves a field (`direction`: 0=up, 1=down) | `form_id`, `field_id`, `direction` |
| `mail_get_template` | Returns the HTML email template for a form | `form_id` |
| `mail_save_template` | Saves the HTML email template | `form_id`, `template_html` |
| `get_reference` | Returns the uCoz template language reference | — |
| `get_guide` | Returns the template architecture guide | — |
| `get_backup_guide` | Returns the backup safety guide | — |

### Tool: `ftp_tool`

Manages site files (CSS, JS, images, etc.) over FTP.

| Action | Description | Required params |
|---|---|---|
| `list` | Lists files and folders at a path | `path` |
| `read` | Reads file contents | `path` |
| `write` | Writes text content to a file | `path`, `content` |
| `mkdir` | Creates a directory | `path` |
| `delete` | Deletes a file or directory | `path` |
| `rename` | Renames or moves a file/directory | `path`, `new_path` |
| `upload` | Uploads a local file to FTP | `local_path`, `remote_path` |

### Common Workflows

**Build a landing page on the home page:**
1. `read_template` (module_id=2, template_id=1) → read current home template
2. `menu_list` → check menus; `menu_update_items` → update navigation with anchor links
3. `ftp_tool: write` → upload CSS and JS files
4. `validate_template` → check HTML without saving
5. `update_template` → save final template (backup created automatically)

**Add a contact form to a page:**
1. `mail_create_form` → create form with name and recipient email
2. `mail_add_field` × N → add fields: name, phone, message
3. `mail_save_template` → customize the email template
4. `update_template` → insert `$MFORM_<ID>$` into the target page template

**Roll back a template:**
1. `list_backups` → get backup list with timestamps
2. `restore_backup` → restore the desired version

---

## Module: Site Pages

Documentation: https://api.ucoz.net/pages.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/pages` | List pages (`page`, `per_page`; max 100 per page) |
| `GET` | `/pages/{id}` | Get a page by ID |
| `POST` | `/pages` | Create a page |
| `PUT` | `/pages` | Update a page (requires `page_id`) |
| `DELETE` | `/pages/{id}` | Delete a page (home page id=1 cannot be deleted) |

**POST/PUT parameters:** `name` (required), `message` (HTML content, required), `parent_id`, `pending` (0/1), `owntmpl` (1 = custom template), `tmpl` (template HTML when owntmpl=1), `ownurl` (slug), `access_all`, `access_group_ids[]`, `meta_title`, `meta_description`, `meta_keywords`, `other1`…`other5`.

---

## Module: Site News

Documentation: https://api.ucoz.net/news.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/news` | List news entries |
| `POST` | `/news` | Add a news entry |
| `PUT` | `/news?id={id}` | Update a news entry |
| `GET` | `/news/category` | List categories |
| `POST` | `/news/category` | Add a category |
| `PUT` | `/news/category?id={id}` | Update a category |
| `GET` | `/news/setup` | Get module settings |
| `PUT` | `/news/setup` | Update module settings |

**POST /news parameters:** `category` (category ID), `title` (up to 130 chars, required), `description` (short text), `message` (full text), `comments` (yes/no), `ontop` (yes/no), `pending` (yes/no), `cover` (base64), `other1`…`other5`.

**PUT /news/category parameters:** `id` (required), `name`, `description`, `hgu_title` (slug), `position`.

---

## Module: Blog

Documentation: https://api.ucoz.net/blog.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/blog` | List blog entries |
| `POST` | `/blog` | Add a blog entry |
| `PUT` | `/blog?id={id}` | Update a blog entry |
| `GET` | `/blog/category` | List categories |
| `POST` | `/blog/category` | Add a category |
| `PUT` | `/blog/category?id={id}` | Update a category |
| `GET` | `/blog/setup` | Get module settings |
| `PUT` | `/blog/setup` | Update module settings |

Parameters mirror the Site News module.

---

## Module: Article Catalog

Documentation: https://api.ucoz.net/publ.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/publ` | List articles |
| `POST` | `/publ` | Add an article |
| `PUT` | `/publ?id={id}` | Update an article |
| `GET` | `/publ/category` | List categories |
| `POST` | `/publ/category` | Add a category |
| `PUT` | `/publ/category?id={id}` | Update a category |

---

## Module: Classifieds Board

Documentation: https://api.ucoz.net/board.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/board` | List listings |
| `POST` | `/board` | Add a listing |
| `PUT` | `/board?id={id}` | Update a listing |
| `GET` | `/board/category` | List categories |
| `POST` | `/board/category` | Add a category |
| `PUT` | `/board/category?id={id}` | Update a category |

---

## Module: Photo Album

Documentation: https://api.ucoz.net/photo.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/photo` | List photos |
| `POST` | `/photo` | Add a photo |
| `PUT` | `/photo?id={id}` | Update a photo |
| `GET` | `/photo/category` | List categories |
| `POST` | `/photo/category` | Add a category |

---

## Module: Video

Documentation: https://api.ucoz.net/video.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/video` | List videos |
| `POST` | `/video` | Add a video |
| `PUT` | `/video?id={id}` | Update a video |
| `GET` | `/video/category` | List categories |
| `GET` | `/video/channel` | List channels |

---

## Module: FAQ

Documentation: https://api.ucoz.net/faq.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/faq` | List Q&A entries |
| `POST` | `/faq` | Add a Q&A entry |
| `PUT` | `/faq?id={id}` | Update an entry |
| `GET` | `/faq/category` | List categories |

---

## Module: Forum

Documentation: https://api.ucoz.net/forum.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/forum` | List forums |
| `GET` | `/forum/topic` | List topics |
| `POST` | `/forum/topic` | Create a topic |
| `GET` | `/forum/message` | List messages |
| `POST` | `/forum/message` | Post a message |
| `PUT` | `/forum/message?id={id}` | Edit a message |

---

## Module: Site Directory

Documentation: https://api.ucoz.net/dir.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/dir` | List entries |
| `POST` | `/dir` | Add an entry |
| `PUT` | `/dir?id={id}` | Update an entry |
| `GET` | `/dir/category` | List categories |

---

## Module: File Catalog

Documentation: https://api.ucoz.net/load.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/load` | List files |
| `POST` | `/load` | Add a file |
| `PUT` | `/load?id={id}` | Update a file entry |
| `GET` | `/load/category` | List categories |

---

## Module: Guest Book

Documentation: https://api.ucoz.net/gb.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/gb` | List entries |
| `POST` | `/gb` | Add an entry |
| `DELETE` | `/gb/{id}` | Delete an entry |

---

## Module: Online Games

Documentation: https://api.ucoz.net/stuff.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/stuff` | List games |
| `POST` | `/stuff` | Add a game |
| `PUT` | `/stuff?id={id}` | Update a game |
| `GET` | `/stuff/category` | List categories |

---

## Module: Users

Documentation: https://api.ucoz.net/user.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/user` | List users |
| `GET` | `/user/{id}` | Get a user by ID |
| `PUT` | `/user/{id}` | Update user data |
| `GET` | `/user/group` | List user groups |
| `GET` | `/user/rank` | List ranks |

---

## Module: Online Shop

Documentation: https://api.ucoz.net/shop.html

### Cart

| Method | Path | Description |
|---|---|---|
| `GET` | `/shop/basket/` | Get cart contents (`user_id` — optional, admins only) |
| `POST` | `/shop/basket/?mode=add` | Add item to cart (`id`, `cnt`, `opt`, `now`) |
| `PUT` | `/shop/basket/?mode=put` | Update item quantity (`id`, `cnt`, `opt`) |
| `DELETE` | `/shop/basket/` | Remove item (`id`); omit `id` to clear entire cart |

### Categories

| Method | Path | Description |
|---|---|---|
| `GET` | `/shop/request?page=categories` | List categories (`parent_id`, `get_globals`) |
| `POST` | `/shop/edit_cat?mode=add` | Add category (`name`, `pid`, `dscr`, `url`, `pos`, `meta_title`, `meta_dscr`, `view_groups`, `add_groups`) |
| `POST` | `/shop/edit_cat?mode=edit` | Edit category (`id` required) |
| `POST` | `/shop/edit_cat?mode=show\|hide` | Show / hide category (`id`) |
| `POST` | `/shop/edit_cat?mode=img` | Manage category image (`id`, `cat_img`, `del`) |

### Products

| Method | Path | Description |
|---|---|---|
| `POST` | `/shop/addgoods` | Add a product (`cat_id` required, `name` required, `brief`, `dscr`, `html_dscr`, `price`, `price_old`, `price_in`, `stock`, `art`, `type`, `hide`, `cats_add`) |

Product types: `0` = physical, `1` = file download, `2` = electronic code, `3` = service.

### Orders

| Method | Path | Description |
|---|---|---|
| `GET` | `/shop/invoices/` | List orders with filters (`page`, `user`, `hide`, `status`, `date`, `id`, `payment`, `delivery`) |
| `PUT` | `/shop/invoices/?mode=hide` | Set order group (`ids`, `hide`: 0=Active, 1=Archived, 2=Trashed) |
| `PUT` | `/shop/invoices/?mode=setCourier` | Assign courier (`ids`, `group_courier`) |
| `PUT` | `/shop/invoices/?mode=status` | Set order status (`ids`, `status`: 0=New, 1=Paying, 2=Paid, 3=Processing, 4=Ready, 5=Shipping, 7=Delivered, 8=Completed, 9=Cancelled) |
| `GET` | `/shop/order/?order={hash}` | Get order by hash |
| `POST` | `/shop/order/?order={hash}` | Add product to existing order (`id`) |
| `PUT` | `/shop/order/?order={hash}&mode=goods` | Update order items (`cnt_REC_ID`, `del_REC_ID`) |
| `PUT` | `/shop/order/?order={hash}&mode=fields` | Update order fields (`field_N`) |
| `PUT` | `/shop/order/?order={hash}&mode=status` | Update order status (`status`) |
| `PUT` | `/shop/order/?order={hash}&mode=note` | Update order note (`note`) |
| `GET` | `/shop/checkout/` | Get checkout data (`promo_code`, `custom_delivery_tax`) |
| `PUT` | `/shop/checkout/?mode=recalc\|edit` | Recalculate or modify pending order |
| `POST` | `/shop/checkout/` | Submit order (`payment_id`, `delivery_id`, `promo_code`, `field_N`) |

### Currency

| Method | Path | Description |
|---|---|---|
| `GET` | `/shop/getshopdata/?page=currencies_list` | List currencies (code, rate, symbol) |
| `POST` | `/shop/setcurrrate` | Update currency rate (`curr_code`, `curr_rate`) |

---

## Module: Subscriptions & Plans

Documentation: https://api.ucoz.net/subscriptions.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/subscriptions` | List plans |
| `GET` | `/subscriptions/user` | List user subscriptions |
| `PUT` | `/subscriptions/user` | Update subscription status |

---

## Design Management & Templates

Documentation: https://api.ucoz.net/templates.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/templates` | Module and template tree (`modules[]` with `id`, `name`, `title`, `items[]`) |
| `GET` | `/templates/{module_id}/{template_id}` | Template HTML and variable list (`content`, `variables[{code, type, description}]`) |
| `PUT` | `/templates/{module_id}/{template_id}` | Update template HTML (`content`) |

**module_id** examples: 6 = News, 7 = Blog, 8 = Forum. Full list from `GET /templates`.

---

## Global Blocks

Documentation: https://api.ucoz.net/gblocks.html

| Method | Path | Description |
|---|---|---|
| `POST` | `/gblocks` | Create a global block (`id`, `pda`) |
| `DELETE` | `/gblocks/{id}` | Delete a global block |

---

## Site Menus

Documentation: https://api.ucoz.net/menus.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/menus` | List all menus |
| `POST` | `/menus` | Create a menu (`title` required, `layout`: 0=horizontal, 1=vertical) |
| `GET` | `/menus/{id}` | Get a menu |
| `PUT` | `/menus/{id}` | Update a menu (`title`, `layout`) |
| `DELETE` | `/menus/{id}` | Delete a menu |
| `PUT` | `/menus/{id}/items` | Replace menu items tree (`items[]`) |

---

## Module Settings

Documentation: https://api.ucoz.net/settings.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/news/setup` | Get News module settings |
| `PUT` | `/news/setup` | Update News module settings |
| `GET` | `/blog/setup` | Get Blog module settings |
| `PUT` | `/blog/setup` | Update Blog module settings |

---

## Mail Forms

Documentation: https://api.ucoz.net/mail-forms.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/mail` | List all mail forms |
| `GET` | `/mail/{form_id}` | Get form details |
| `POST` | `/mail` | Create a form (`name` up to 73 chars, `emails`, `rez`) |
| `PUT` | `/mail/{form_id}` | Update a form |
| `DELETE` | `/mail/{form_id}` | Delete a form |
| `GET` | `/mail/{form_id}/fields` | List form fields |
| `POST` | `/mail/{form_id}/fields` | Add a field (`name`, `type` 1–8, `required`, `values`) |
| `PUT` | `/mail/{form_id}/fields/{field_id}` | Update a field |
| `DELETE` | `/mail/{form_id}/fields/{field_id}` | Delete a field |
| `PUT` | `/mail/{form_id}/fields/{field_id}/move` | Move a field (`direction`: 0=up, 1=down) |
| `GET` | `/mail/{form_id}/template` | Get the email HTML template |
| `POST` | `/mail/{form_id}/template` | Save the email HTML template (`tmpl`) |

**Field types:** 1=text, 2=textarea, 3=checkbox, 4=radio, 5=select, 6=file, 7=captcha, 8=privacy policy.

---

## Minichat

Documentation: https://api.ucoz.net/mchat.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/mchat` | List messages |
| `POST` | `/mchat` | Post a message |
| `DELETE` | `/mchat/{id}` | Delete a message |
| `GET` | `/mchat/smiles` | List emoticons |

---

## Polls

Documentation: https://api.ucoz.net/polls.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/polls` | List polls |
| `POST` | `/polls` | Create a poll |
| `PUT` | `/polls/{id}` | Update a poll |
| `DELETE` | `/polls/{id}` | Delete a poll |
| `POST` | `/polls/{id}/vote` | Submit a vote |

---

## Site Search

Documentation: https://api.ucoz.net/search.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/search?query={q}` | Full-text search across the entire site |
| `GET` | `/search?query={q}&module={m}` | Search within a specific module |

---

## Comments & Extra Methods

Documentation: https://api.ucoz.net/other.html

| Method | Path | Description |
|---|---|---|
| `GET` | `/comments` | List comments from all modules |
| `DELETE` | `/comments/{id}` | Delete a comment |
| `PUT` | `/comments/{id}` | Edit a comment |

---

## Response Format

All responses are JSON. A successful response contains a `success` object; an error response contains an `error` object.

```json
// Success
{ "success": { ... } }

// Error
{ "error": { ... } }
```

## Error Codes

Full list: https://api.ucoz.net/errors.html

## Usage Examples

Full request examples: https://api.ucoz.net/examples.html

PHP module for uAPI: https://api.ucoz.net/ (section «PHP Module»)