Перейти к основному содержимому

Публичный API

Публичный API позволяет внешним системам публиковать посты, получать проекты и каналы, загружать медиа и управлять публикацией.

Базовый префикс:

/api/public/v1

Интерактивный справочник эндпоинтов — в разделе API документации: кратко о справочнике.

Аутентификация​

Используется Bearer API-ключ:

Authorization: Bearer pmt_live_xxxxxxxxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Ключи создаются в приложении: Автоматизация → API (сейчас пункт виден только администраторам, beta). После создания ключ используется в заголовке Authorization: Bearer … для запросов к /api/public/v1.

Rate limit​

Лимиты считаются по API-ключу (отдельные счётчики на категорию):

  • Загрузка файлов (POST .../media): 10 запросов в минуту
  • Создание поста (POST .../posts): 10 запросов в минуту
  • Публикация поста (POST .../posts/{id}/publish): 10 запросов в минуту
  • Остальные методы (списки проектов, каналов, постов, usage): 30 запросов в минуту

Заголовки ответа:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • Retry-After (при 429)

Эндпоинты​

1) Проекты​

GET /api/public/v1/projects

Возвращает проекты, к которым ключ имеет доступ (владелец или участник команды).

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

{
  "items": [
    {
      "id": 101,
      "name": "Основной проект",
      "timezone": "Europe/Moscow",
      "created_at": "2026-01-10T08:42:00.000000",
      "is_owner": true
    }
  ],
  "count": 1
}

2) Каналы проекта​

GET /api/public/v1/projects/{project_id}/channels

Возвращает каналы всех подключенных аккаунтов проекта.

id канала в ответе имеет формат:

{platform}:{account_id}:{channel_id}

Пример:

{
  "items": [
    {
      "id": "telegram:12:-1001234567890",
      "platform": "telegram",
      "account_id": 12,
      "channel_id": "-1001234567890",
      "title": "Новости",
      "username": "news_channel",
      "needs_reconnect": false
    }
  ],
  "count": 1
}

3) Загрузка файлов​

POST /api/public/v1/projects/{project_id}/media

Вариант 1 — файл с диска: multipart/form-data, поле files, ровно один файл на запрос. Несколько файлов — несколько запросов. Больше одного файла в multipart → 400 too_many_files.

Вариант 2 — по ссылке: Content-Type: application/json, тело {"url":"https://...","filename":"optional.jpg"}. Сервер скачивает ресурс (таймаут 30 с, максимум 50 МБ), кладёт в то же хранилище и создаёт MediaAsset. URL должен быть http(s) с обычным хостом; localhost и приватные IP в hostname отклоняются.

В сгенерированной из OpenAPI документации (Try it / Request) у этого же POST .../media нужно переключить тип тела с multipart/form-data на application/json — тогда появится схема с полем url и примеры «Загрузка по HTTPS-ссылке».

Пример multipart:

curl -X POST "https://your-domain/api/public/v1/projects/101/media" \
  -H "Authorization: Bearer pmt_live_xxx.yyy" \
  -F "files=@/path/to/image1.jpg"

Пример по URL:

curl -X POST "https://your-domain/api/public/v1/projects/101/media" \
  -H "Authorization: Bearer pmt_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/image.jpg","filename":"image.jpg"}'

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

{
  "items": [
    {
      "id": 501,
      "type": "image",
      "filename": "image1.jpg",
      "mime_type": "image/jpeg",
      "size_bytes": 152343,
      "url": "https://.../uploads/user_1/....jpg",
      "minio_path": "user_1/....jpg",
      "created_at": "2026-04-30T18:19:10.000000"
    }
  ],
  "count": 1
}

4) Создание поста​

POST /api/public/v1/projects/{project_id}/posts

Тело:

{
  "text": "Пост через API",
  "targets": [
    { "channel_ref": "telegram:12:-1001234567890" }
  ],
  "media_ids": [501, 502],
  "scheduled_at": "2026-05-01T10:00:00Z",
  "publish_now": false
}

Поле media_ids — не больше 10 элементов на один пост (лимит альбома Telegram).

Если scheduled_at задан, пост создается в scheduled.
Если publish_now=true, пост сразу отправляется в очередь публикации.

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

{
  "id": 9001,
  "status": "scheduled",
  "project_id": 101,
  "text": "Пост через API",
  "scheduled_at": "2026-05-01T10:00:00",
  "created_at": "2026-04-30T18:23:44.000000"
}

5) Список постов​

GET /api/public/v1/projects/{project_id}/posts?limit=50

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

{
  "items": [
    {
      "id": 9001,
      "status": "scheduled",
      "text": "Пост через API",
      "platform": "telegram",
      "channel_ids": ["-1001234567890"],
      "scheduled_at": "2026-05-01T10:00:00",
      "published_at": null,
      "created_at": "2026-04-30T18:23:44.000000"
    }
  ],
  "count": 1
}

6) Публикация существующего поста​

POST /api/public/v1/projects/{project_id}/posts/{post_id}/publish

У поста в media_files не должно быть больше 10 файлов, иначе 400 с кодом too_many_media_files.

Тело:

{
  "targets": [
    { "channel_ref": "telegram:12:-1001234567890" }
  ]
}

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

{
  "id": 9001,
  "status": "publishing"
}

7) Usage​

GET /api/public/v1/usage

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

{
  "posts_this_month": 12,
  "projects_count": 3,
  "api_keys_count": 2
}

Ошибки​

Формат ошибок:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Required scope is missing"
  }
}

Типичные коды:

  • unauthorized (401) — отсутствует/невалидный API-ключ
  • insufficient_scope (403) — ключ без нужного scope
  • forbidden (403) — нет прав в проекте
  • project_not_found (404) — проект недоступен
  • post_not_found (404) — пост не найден
  • rate_limit_exceeded (429) — превышен лимит запросов