API документация

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

Все запросы к /api/v1/* требуют API-ключ. Получить его можно в личном кабинете → раздел «API ключи».

Ключ передаётся в заголовке Authorization:

Authorization: Bearer npk_ваш_ключ_здесьКопировать

Base URL

https://na-potom.ru/api/v1Копировать

Все запросы и ответы используют Content-Type: application/json.

Ошибки

При ошибке сервер возвращает JSON с полем detail:

{
  "detail": "Card not found"
}

Ограничения

• Максимум 10 заметок одновременно в очереди на обработку
• Максимальный размер контента заметки: 50 000 символов
• Список карточек: максимум 100 за один запрос (limit)

Заметки

Заметка — это сырой контент (текст, ссылка, идея), который AI обрабатывает и превращает в карточку. После отправки заметки нужно отдельно опросить статус.

{
  "task_id": 42,
  "status": "queued",
  "queue_position": 1
}

{
  "id": 42,
  "status": "done",
  "queue_position": 0,
  "result_card_id": 17,
  "pipeline_stage": "done",
  "moderation_failed": false,
  "moderation_reason": "",
  "result_action": "created_new",
  "result_message": "Создана новая карточка «FastAPI»."
}

Карточки

Карточка — результат обработки заметки: заголовок, AI-описание, категория, теги, ссылка.

[
  {
    "id": 17,
    "title": "FastAPI",
    "summary": "Современный высокопроизводительный веб-фреймворк...",
    "url": "https://github.com/fastapi/fastapi",
    "original_content": "https://github.com/fastapi/fastapi",
    "is_public": true,
    "created_at": "2026-04-17T05:14:07.746956",
    "updated_at": "2026-04-17T05:14:07.746962",
    "category_name": "Разработка / Backend",
    "category_slug": "development-backend",
    "category_color": "#10b981",
    "tags": ["developer-tools", "open-source"]
  }
]Копировать

{ "card_id": 17, "is_public": true }

{ "card_id": 17, "deleted": true }

Категории

[
  {
    "id": 3,
    "name": "Разработка / Backend",
    "slug": "development-backend",
    "color": "#10b981",
    "card_count": 12
  }
]

Теги

[
  { "name": "python",         "count": 8 },
  { "name": "developer-tools","count": 5 },
  { "name": "open-source",    "count": 3 }
]

Статистика

{
  "total_cards": 42,
  "public_cards": 18,
  "private_cards": 24,
  "categories_count": 7
}

Примеры — cURL

Замените npk_ваш_ключ на свой API-ключ из личного кабинета.

Добавить ссылку в каталог

curl -X POST https://na-potom.ru/api/v1/notes \
  -H "Authorization: Bearer npk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"content": "https://example.com/article"}'Копировать

Проверить статус задачи

curl https://na-potom.ru/api/v1/notes/42/status \
  -H "Authorization: Bearer npk_ваш_ключ"Копировать

Получить список карточек с фильтром

curl "https://na-potom.ru/api/v1/cards?limit=10&tags=python,ai" \
  -H "Authorization: Bearer npk_ваш_ключ"Копировать

Опубликовать карточку

curl -X PATCH https://na-potom.ru/api/v1/cards/17/visibility \
  -H "Authorization: Bearer npk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"is_public": true}'Копировать

Примеры — Python

import requests
import time

API_KEY = "npk_ваш_ключ"
BASE = "https://na-potom.ru/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def add_note(content: str) -> int:
    """Добавить заметку и вернуть ID карточки после обработки."""
    resp = requests.post(f"{BASE}/notes",
                         json={"content": content},
                         headers=HEADERS)
    resp.raise_for_status()
    task_id = resp.json()["task_id"]

    # Ждём пока AI обработает
    for _ in range(30):
        time.sleep(5)
        status = requests.get(f"{BASE}/notes/{task_id}/status",
                              headers=HEADERS).json()
        if status["status"] == "done":
            return status["result_card_id"]
        if status["status"] in ("failed", "moderation_failed"):
            raise RuntimeError(status.get("result_message"))

    raise TimeoutError("Обработка заняла слишком много времени")

card_id = add_note("https://github.com/fastapi/fastapi")
print(f"Карточка создана: {card_id}")

# Получить список всех карточек
cards = requests.get(f"{BASE}/cards", headers=HEADERS).json()
for c in cards:
    print(c["title"], c["category_name"])Копировать

Примеры — iOS Shortcuts

Создайте шорткат «Поделиться в NaPotom» для добавления ссылок прямо из браузера:

1. Создайте новый шорткат в приложении «Команды»
2. Добавьте действие «Получить URL из ввода»
3. Добавьте действие «Получить содержимое URL» с настройками:
   • URL: https://na-potom.ru/api/v1/notes
   • Метод: POST
   • Заголовки: Authorization: Bearer npk_ваш_ключ
   • Тело (JSON): {"content": "[URL из шага 1]"}
4. Добавьте действие «Уведомление» с текстом «Добавлено в NaPotom»
5. В настройках шортката включите «Показывать в меню Поделиться»

После этого на любой странице Safari нажмите «Поделиться» → найдите ваш шорткат — ссылка уйдёт в обработку.