Markdown prompt
# Postify API Card Template
Заполни этот шаблон строго по полям. Не добавляй лирику. Если данных нет — пиши "TODO".
## 1. Identity
id: kebab-case уникальный slug для URL /api-docs/{id}
title: короткое название API
method: GET | POST
endpoint: путь frontend/BFF, который будет дёргать сайт
status: draft | ready | deprecated
owner: AI | backend | frontend ответственные
## 2. Purpose
description: 1 предложение, что делает API
useCases:
- где на сайте вызывается
- какой пользовательский сценарий закрывает
## 3. Site Request
siteRequest:
- какие поля сайт обязан отправить
- какие поля backend берёт сам из сессии/БД
- какие поля опциональные
## 4. Frontend Logic
frontendLogic:
- что показать до запроса
- что сделать при success
- что сделать при error
- нужен ли polling/stream/webhook
## 5. Backend Logic
backendLogic:
- валидация
- какие таблицы/сервисы прочитать
- какой AI/provider вызвать
- что сохранить
- что вернуть
## 6. Contract
input:
- field: type — описание
success:
- field: type — описание
errors:
- code — когда возникает, retryable true/false
## 7. Test
Главная цель — кнопка "Проверить API" должна работать сразу после реализации backend.
testPath: путь для тестового запроса
testBody: JSON body или null для GET
mockOutput: рыбный ответ, похожий на реальный результат
## 8. Examples
curl: минимальный curl
fetch: минимальный frontend fetch
JSON форма
{
"id": "video-generate",
"title": "Генерация видео",
"method": "POST",
"endpoint": "/api/video/jobs",
"description": "Создаёт задачу генерации видео и возвращает jobId.",
"input": [
"brandId: string",
"postId?: string",
"script?: string",
"mode: avatar | regular"
],
"siteRequest": [
"brandId",
"postId или script",
"mode",
"accessToken берётся из сессии"
],
"frontendLogic": [
"Показать loading",
"Сохранить jobId",
"Запустить polling статуса",
"Показать videoUrl"
],
"backendLogic": [
"Проверить бренд",
"Создать job",
"Вызвать AI provider",
"Сохранить результат"
],
"success": [
"jobId: string",
"status: queued | running",
"estimatedSeconds?: number"
],
"errors": [
"brand_not_ready — retryable false",
"provider_unavailable — retryable true"
],
"testPath": "/api/video/jobs",
"testBody": {
"brandId": "brand_123",
"postId": "post_456",
"mode": "regular"
},
"mockOutput": {
"jobId": "job_demo",
"status": "queued",
"sampleVideo": "https://cdn.example/video.mp4"
},
"curl": "curl -X POST ...",
"fetch": "const res = await fetch(...)"
}