Поделиться папкой с кодом

POST/api/v1/folders

Доступ: Ключ API
Право: content:write

ZIP папки; сервер оставляет только текстовые файлы и перечисляет остальное в folder.skipped с причиной: зависимости, сборка, служебные папки, секреты (не сохраняются никогда), .gitignore из корня, недопустимые в Windows имена, слишком глубокие пути, большие файлы, совпадения имён без учёта регистра и не текст по содержимому. Сохранённое — новый ZIP; в квоту идут его байты. Доступ, срок, пароль и одноразовое открытие — как у файлов.

Пример запроса

curl -X POST "https://lac.pics/api/v1/folders" \
  -H "Authorization: Bearer lac_api_YOUR_KEY" \
  -H "Idempotency-Key: folder-2026-09-28-my-app-1" \
  -F "file=@my-app.zip" \
  -F "visibility=unlisted"

Параметры

Заголовки

Idempotency-Keystring
Случайная строка из 16–128 латинских букв, цифр, _ и -, одна на файл. Повтор с тем же ключом и теми же данными вернёт уже загруженный файл (201) и не продлит его срок; квитанции хранятся не меньше 24 часов. Попытка ещё идёт — 409 с Retry-After; тот же ключ с другими данными — 409; файл уже удалён или истёк — 410. Без заголовка каждый запрос — новая загрузка.
шаблон ^[A-Za-z0-9_-]{16,128}$

Тело запроса

multipart/form-dataобязательный

filestring · binaryобязательный
ZIP папки, до 32 МБ: без пароля, с именами в UTF-8, без путей вроде ../. Имя архива без .zip — название, если title не передан.
tagsstring
Массив строк в JSON, например ["demo","nextjs"]; правила те же, что у тегов в JSON.
не длиннее 2 048
titlestring
Название, до 180 символов.
не длиннее 180
visibilitystring
private — только ты; unlisted — все, у кого есть ссылка; public — ещё лента и профиль, нельзя вместе с oneTime (400 ONE_TIME_NOT_PUBLIC). Не передано при создании — настройка аккаунта; при изменении — доступ прежний.
значения: "private" "unlisted" "public"
ttlstring
Срок хранения от момента запроса: day, week, month или forever — без срока. После него ссылка перестаёт открываться, зашифрованные данные удаляются в фоне.
значения: "forever" "day" "week" "month"
passwordstringтолько в запросе
8–128 символов. Пустая строка снимает пароль, без поля пароль не меняется. Хранится как Argon2id и не возвращается; смена закрывает доступ тем, кто уже открывал. В ленте, профилях и альбомах другие видят такой файл закрытой карточкой.
не длиннее 128 · шаблон ^(?:[\s\S]{8,128})?$
oneTimeboolean
Файл откроет только первый гость — не дольше 10 минут, включая перемотку видео. Твой просмотр и запросы GET/HEAD ссылку не тратят. Нельзя вместе с public; в ленте, профилях и альбомах такой файл не показывается.
по умолчанию false

Ответы

201СозданоCreatedFolder
- idstringобязательный
  id файла.
- titlestringобязательный
  Название.
- tagsмассив stringобязательный
  Теги.
  до 10 элементов · без повторов
- originalNamestring
  Исходное имя файла.
- typestringобязательный
  IMAGE, VIDEO, PASTE или FOLDER — папка с кодом.
  значения: "IMAGE" "VIDEO" "PASTE" "FOLDER"
- mimestringобязательный
  MIME-тип сохранённого файла.
- pasteFormatstringили null
  Формат заметки.
  значения: "plain" "markdown" "code"
- pasteLanguagestringили null
  Язык подсветки заметки.
- folderFilesintegerили null
  У папки с кодом — сколько в ней файлов; у остального null.
  от 1
- revisionintegerобязательный
  Ревизия текста заметки для правки.
  от 1
- accessVersionintegerобязательный
  Share access version: 1 for a new file, raised by every change of visibility, password or one-time. From 2 on, url carries it as ?v= so messengers build a fresh link card instead of the one they kept for the previous access.
  от 1
- sizeinteger · int64обязательный
  Размер в байтах.
- visibilitystringобязательный
  Доступ: private, unlisted или public.
  значения: "private" "unlisted" "public"
- allowDownloadbooleanобязательный
  Показывается ли кнопка скачивания.
- passwordProtectedbooleanобязательный
  Есть ли пароль.
- oneTimebooleanобязательный
  Одноразовая ли ссылка.
- consumedAtstring · date-timeили null
  Когда одноразовая ссылка была открыта.
- readExpiresAtstring · date-timeили null
  До какого момента открывший одноразовую ссылку может смотреть файл.
- readMaxExpiresAtstring · date-timeили null
  Самый поздний конец доступа по одноразовой ссылке.
- hasVideoTextboolean
  Есть ли у видео субтитры или расшифровка.
- videoTextRevisioninteger
  Ревизия текста видео.
  0–2 147 483 647
- viewsintegerобязательный
  Засчитанные открытия гостями, без повторов в пределах доступа зрителя (обычно сутки). Просмотры владельца не считаются.
  от 0
- viewLimitintegerили null
  Лимит просмотров (Pro) или null.
  1–1 000 000
- viewLimitReachedAtstring · date-timeили null
  Когда лимит просмотров исчерпан; null, пока просмотры есть или лимита нет.
- mediaStatusstring
  Обработка: PROCESSING — идёт, READY — готово, FAILED — не удалась. Воспроизведение и превью — после READY; оригинал владелец может скачать и раньше, с ?download=1.
  значения: "PROCESSING" "READY" "FAILED"
- mediaErrorstringили null
  Причина, если обработка не удалась.
- widthintegerили null
  Ширина в пикселях.
- heightintegerили null
  Высота в пикселях.
- durationMsintegerили null
  Длительность видео в миллисекундах.
- videoCodecstringили null
  Кодек видео.
- hasAudioboolean
  Есть ли звук.
- previewUrlstringили null
  Адрес зашифрованного превью; доступ — как у самого файла.
- expiresAtstring · date-timeили null
  Когда файл и ссылка перестанут работать; null — без срока.
- createdAtstring · date-timeобязательный
  Когда создан.
- urlstring · uriобязательный
  Ссылка на страницу файла.
- mediaUrlstringобязательный
  Адрес самого файла.
- moderationHoldstringили null
  Автопроверка: review — скрыт до решения модератора, blocked — скрыт модератором. Другие видят такой файл как приватный.
  значения: "review" "blocked"
- favoriteboolean
  В избранном (в списках).
- ownedboolean
  Свой файл (в списках).
- authorobject
  Автор.
  3 поля
  - idstring
    id автора.
  - usernamestring
    Никнейм.
  - namestring
    Имя.
- contentContent
  Файл.
  то же, что Content выше
- folderobjectобязательныйили null
  What the server kept and left out. Null when an Idempotency-Key replay returns the folder made before.
  5 полей
  - filesintegerобязательный
    от 1
  - textBytesintegerобязательный
    от 0
  - skippedмассив FolderSkipобязательный
    Sorted by path; the first 200.
    до 200 элементов
    FolderSkip 4 поля
    pathstringобязательный
    A file, or a whole folder when it ends with «/».
    reasonstringобязательный
    dependencies (node_modules, vendor of a package manager, .venv…), build (dist, build, out, target, .next, bin/obj of .NET, coverage, caches…), service (.git, .svn, .hg, .idea, .vs), secret (.env* except .env.example, *.pem, *.key, id_rsa*, credentials*, token files, or a private key inside), gitignore (the root .gitignore), name (a name Windows cannot create), path (too deep or long), large (a file over the size limit), duplicate (a name that differs only by case), binary (not UTF-8 text by its bytes).
    значения: "dependencies" "build" "service" "secret" "gitignore" "name" "path" "large" "duplicate" "binary"
    filesintegerобязательный
    от 1
    sizeintegerобязательный
    Размер в байтах.
    от 0
  - skippedFilesintegerобязательный
    от 0
  - gitignorestringобязательный
    Whether the root .gitignore was applied: none without a readable one, complex when its patterns needed too much work (then it is not applied at all).
    значения: "applied" "none" "complex"
400Некорректный запросFOLDER_ARCHIVE_INVALID FOLDER_EMPTY ONE_TIME_NOT_PUBLIC
401Нужен действующий ключ
403Нет права или функции тарифа
404Не найдено
408Тело запроса перестало приходить
409Конфликт
410Файл удалён или истёк
413Слишком большой файл или нет местаFOLDER_TOO_LARGE FOLDER_TOO_MANY_FILES UPLOAD_TOO_LARGE
422FOLDER_INFECTEDFOLDER_INFECTED
429Слишком много запросов
503Сервис занят или недоступен

Пример ответа

201 · application/json

{
  "id": "Xq3u9RkT0bLmA7cV2pWz1eFy",
  "title": "capture",
  "tags": [
    "release"
  ],
  "originalName": "capture.png",
  "type": "IMAGE",
  "mime": "image/png",
  "pasteFormat": null,
  "pasteLanguage": null,
  "folderFiles": 1,
  "revision": 1,
  "accessVersion": 1,
  "size": 482133,
  "visibility": "unlisted",
  "allowDownload": true,
  "passwordProtected": false,
  "oneTime": false,
  "consumedAt": null,
  "readExpiresAt": null,
  "readMaxExpiresAt": null,
  "hasVideoText": false,
  "videoTextRevision": 0,
  "views": 3,
  "viewLimit": null,
  "viewLimitReachedAt": null,
  "mediaStatus": "READY",
  "mediaError": null,
  "width": 1920,
  "height": 1080,
  "durationMs": null,
  "videoCodec": null,
  "hasAudio": false,
  "previewUrl": null,
  "expiresAt": null,
  "createdAt": "2026-09-27T09:30:00.000Z",
  "url": "https://lac.pics/s/Xq3u9RkT0bLmA7cV2pWz1eFy",
  "mediaUrl": "/api/media/Xq3u9RkT0bLmA7cV2pWz1eFy",
  "moderationHold": null,
  "favorite": false,
  "owned": true,
  "author": {
    "id": "cmf8a1x2k0000q7lh3v9w2e4d",
    "username": "alex",
    "name": "Alex"
  },
  "folder": {
    "files": 1,
    "textBytes": 0,
    "skipped": [
      {
        "path": "string",
        "reason": "dependencies",
        "files": 1,
        "size": 482133
      }
    ],
    "skippedFiles": 0,
    "gitignore": "applied"
  }
}

Коды ошибок

Код	Статус	Текст
`FOLDER_ARCHIVE_INVALID`	400	Не удалось прочитать архив папки: нужен обычный ZIP без пароля, с именами в UTF-8 и без путей вроде «../».
`FOLDER_EMPTY`	400	В папке не осталось файлов для загрузки: зависимости, сборка, секреты и не текст не загружаются.
`ONE_TIME_NOT_PUBLIC`	400	Одноразовый файл нельзя опубликовать в ленте и профиле. Выбери доступ по ссылке или отключи одноразовую ссылку.
`FOLDER_TOO_LARGE`	413	Текста в папке больше 20 МБ. Выбери папку поменьше или исключи лишнее в .gitignore.
`FOLDER_TOO_MANY_FILES`	413	Можно до 2 000 файлов. Выбери папку поменьше или исключи лишнее в .gitignore.
`UPLOAD_TOO_LARGE`	413	Файл больше допустимого размера.
`FOLDER_INFECTED`	422	Антивирус нашёл угрозу в папке, поэтому она не загружена.

Ответы любого метода с ключом — неверный или истёкший ключ, нет права, частые запросы — в разделе Ошибки.