Admin API: landing pages

With these methods an integration does the same as the Landing pages («Лендинги») section and the file editor in the panel: creates landing pages, uploads archives, edits files and saves versions. How landing pages work in the panel is described on the Landing pages page.

General rules

• All methods on this page require a token with Full access («Полный доступ») (full). Connecting and the Api-Key header are described on the Admin API: overview and authorization page, and the request and error format on the Request, response and error format page.
• {id} in the address is the landing page ID in UUID format, the id field from the response.
• For an unknown or deleted landing page, the server responds with 404 and the not_found code. For an ID not in UUID format — 400 with the bad_request code and the message некорректный идентификатор или значение (invalid ID or value).
• File paths are relative to the root of the landing page folder, with forward slashes: index.html, css/style.css.
• Files and folders whose names start with a dot are not read or written. The response is 400, bad_request, скрытые файлы (начинающиеся с точки) не поддерживаются (hidden files, starting with a dot, are not supported).
• A path outside the landing page folder gives 400, bad_request, недопустимый путь (invalid path).

Landing page object

{
  "id": "5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a",
  "name": "Prelander DE",
  "url": "https://example.com/lp?cid={click_id}",
  "files_path": null,
  "type": "prelander",
  "storage": "external",
  "owner_id": "9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "seq": 12
}

List and read

List landing pages

GET /api/v1/landers

Returns all of the team's landing pages except deleted ones. Newest first.

Response — 200 and an array of landing page objects. If there are no landing pages, the array is empty.

Get a landing page

GET /api/v1/landers/{id}

Returns one landing page.

Response — 200 and a landing page object.

Create, edit and delete

Create a landing page

POST /api/v1/landers

Creates a landing page. The user who created the token becomes its owner.

Response — 201 and a landing page object.

Errors:

• 400, bad_request, invalid json — the body was not parsed;
• 422, validation, name is required — no name.

curl -X POST https://panel.example.com/api/v1/landers \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Prelander DE","url":"https://example.com/lp?cid={click_id}"}'

Edit a landing page

PUT /api/v1/landers/{id}

Changes the name, address, type and storage kind. Fields not in the body keep their previous values.

This method does not change the files_path field.

Response — 200 and a landing page object.

Errors:

• 400, bad_request, invalid json;
• 422, validation, name is required — the name was passed empty;
• 422, validation, url is required for external lander — a filled-in address of an external landing page is being cleared, or a hosted landing page without an address is being switched to external.

Delete a landing page

DELETE /api/v1/landers/{id}

Moves the landing page and its files to the trash. Restore it with the methods on the Admin API: trash page.

Response — 204 with no body.

Copy and access

Clone a landing page

POST /api/v1/landers/{id}/clone

Creates a copy named <name> (копия), where копия means “copy”. For a hosted landing page, the files are copied too.

You do not have to send a body.

Response — 201 and the new landing page object.

Who the landing page is shared with

GET /api/v1/landers/{id}/shares

Returns the users who can view the landing page.

Response — 200:

{"user_ids": ["9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d"]}

Set access to a landing page

POST /api/v1/landers/{id}/shares

Replaces the list of users who can view the landing page. User IDs are returned by Admin API: users.

Response — 204 with no body.

Errors: 400, bad_request, invalid json.

Uploading an archive and files

Both methods accept multipart/form-data. Limits: 1 GB per request, 1 GB per file, 1 GB per unpacked archive, 10,000 files per landing page. Archive requirements are on the Hosted pages page.

Upload an archive

POST /api/v1/landers/{id}/upload

Unpacks a ZIP into the landing page folder. The previous files are replaced with the archive contents. If the landing page already had files, they are saved as a version before the replacement. If the archive is not accepted, the previous files stay in place. An external landing page becomes hosted after the upload.

Response — 200 and the list of files after unpacking:

{"files": [{"path": "index.html", "size": 4812, "dir": false}]}

Errors:

• 400, bad_request, не удалось прочитать форму (загрузка прервана или повреждена) (could not read the form: the upload was interrupted or corrupted);
• 413, too_large, превышен лимит загрузки 1 ГБ (the 1 GB upload limit was exceeded);
• 413, too_large, слишком много файлов (too many files);
• 413, too_large, файл слишком большой (лимит 1 ГБ на файл, 1 ГБ на распакованный архив) (file too large: limit 1 GB per file, 1 GB per unpacked archive);
• 422, validation, ожидался файл в поле archive (a file was expected in the archive field);
• 422, validation, файл не является корректным .zip (the file is not a valid .zip);
• 422, validation, архив сжат неподдерживаемым методом (LZMA, AES-шифрование и т.п.) — пересоберите обычным ZIP без пароля (the archive uses an unsupported compression method, such as LZMA or AES encryption — rebuild it as a regular ZIP without a password);
• 422, validation, архив повреждён — пересоберите его и загрузите заново (the archive is corrupted — rebuild it and upload it again).

curl -X POST https://panel.example.com/api/v1/landers/5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a/upload \
  -H "Api-Key: <token>" \
  -F "[email protected]"

Upload additional files

POST /api/v1/landers/{id}/files

Adds one or more files to those already uploaded. A file with the same path is overwritten; the others do not change. An external landing page becomes hosted.

Response — 200:

{
  "files": [{"path": "img/hero.jpg", "size": 182044, "dir": false}, {"path": "index.html", "size": 4812, "dir": false}],
  "saved": ["img/hero.jpg"],
  "storage": "local"
}

files — all files of the landing page, saved — the paths of the files just saved.

Errors:

• 400, bad_request — the form or one of the files could not be read, or the path is invalid;
• 413, too_large — the request, file or file count limit was exceeded;
• 422, validation, ожидались файлы в поле files (files were expected in the files field);
• 422, validation, нечего сохранять (nothing to save).

Landing page files

Reading and writing content is meant for text files up to 5 MB. Upload larger files and images with the methods in the Uploading an archive and files section.

List files

GET /api/v1/landers/{id}/files

Returns the landing page's files sorted by path. Folders are not listed as separate rows.

Response — 200:

{"files": [{"path": "css/style.css", "size": 2210, "dir": false}, {"path": "index.html", "size": 4812, "dir": false}]}

For a landing page without files, the array is empty.

Read a file

GET /api/v1/landers/{id}/file?path=index.html

Returns the file's content.

Response — 200:

Errors:

• 404, not_found, файл не найден (file not found);
• 413, too_large, файл больше 5 МБ — Редактор такие не открывает и не сохраняет; замените его загрузкой файла или архива (the file is larger than 5 MB — the editor does not open or save such files; replace it by uploading a file or an archive);
• 422, validation, path is required.

Create or save a file

PUT /api/v1/landers/{id}/file

Writes a text file. Missing folders are created. An external landing page becomes hosted.

Response — 200:

{"ok": true, "storage": "local"}

Errors:

• 400, bad_request, invalid json;
• 409, conflict, файл с таким путём уже есть (a file with this path already exists);
• 413, too_large — the content is larger than 5 MB or the landing page already has 10,000 files;
• 422, validation, path is required.

Rename a file

POST /api/v1/landers/{id}/rename

Renames a file or moves it to another folder of the landing page. An existing file at the new path is not overwritten. A file named leads.php is not renamed: the response is 400.

Response — 200:

{"ok": true}

Errors: 400, bad_request, нужны исходный и новый путь (the source and new paths are required).

Delete a file

DELETE /api/v1/landers/{id}/file?path=old.html

Deletes one file.

Response — 204 with no body.

Errors:

• 404, not_found, файл не найден (file not found);
• 422, validation, path is required.

Versions and archive

A version is a saved snapshot of all the landing page's files. The 10 latest versions are kept; older ones are deleted when a new one is saved. Files and folders whose names start with a dot and the leads.php file do not go into versions or the archive. Saving a version and downloading the archive are meant for a landing page that has files. The same actions in the panel are described on the File editor, versions and export page.

List versions

GET /api/v1/landers/{id}/versions

Returns the saved versions, newest first.

Response — 200 and an array:

If there are no versions, the array is empty.

Save a version

POST /api/v1/landers/{id}/versions

Saves the current files as a new version. No body is needed.

Response — 201 and a version object with the id, created_at, size fields.

Errors: 413, too_large — the landing page has more than 10,000 files or more than 1 GB.

Restore a version

POST /api/v1/landers/{id}/versions/{version}/restore

Replaces the landing page's files with the version's files. {version} is the id field from the version list. Before the replacement, the current files are saved as a new version. No body is needed.

Response — 200:

{"ok": true}

Download the archive

GET /api/v1/landers/{id}/archive

Returns the landing page's current files as a single ZIP.

Response — 200, content type application/zip, file name page.zip.

curl https://panel.example.com/api/v1/landers/5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a/archive \
  -H "Api-Key: <token>" \
  -o page.zip

Errors: 413, too_large — the landing page has more than 10,000 files or more than 1 GB.