Документация API Inkpilots V1

Назначение: Полный справочник по публичному API V1 с подробным описанием эндпоинтов, параметров запросов, аутентификации, форматов ответов и системы квот для генерации Node.js SDK.

Содержание

Аутентификация
Базовый URL и CORS
Эндпоинты API
Обработка ошибок
Система квот
Форматы ответов
Сводка эндпоинтов

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

Аутентификация по API-ключу

Все эндпоинты API V1 требуют аутентификации через API-ключ. API-ключ передаётся в заголовке запроса.

Формат заголовка:

x-api-key: Bearer <your-api-key>

Пример:

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

Процесс проверки

Клиент отправляет запрос с заголовком x-api-key
Сервер вызывает функцию verifyApiKey(apiKeyHeader)
Если ключ валиден, возвращается:
- isValid: boolean
- workspaceId: string (MongoDB ObjectId в виде строки)
Если ключ невалиден, возвращается { isValid: false }

Ответы с ошибками

401 Unauthorized: Неверный или отсутствующий API-ключ, либо недостаточно прав
402 Payment Required: Превышена квота API-доступа для тарифа рабочего пространства

Базовый URL и CORS

Базовый URL

https://inkpilots.com/api/v1

Заголовки CORS

Все ответы включают следующие заголовки CORS:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

Примечание: CORS разрешает все источники, потому что API не использует cookie (stateless-аутентификация).

Preflight-запросы

Все эндпоинты поддерживают запросы OPTIONS для CORS preflight:

curl -X OPTIONS https://inkpilots.com/api/v1/agents

Ответ: 204 No Content с заголовками CORS.

Эндпоинты API

1. Список агентов

Endpoint: GET /agents

Кратко: Получить список агентов

Описание: Возвращает пагинированный список агентов с расширенной фильтрацией по статусу, режиму выполнения, LLM-модели и полнотекстовым поиском по имени и промпту. Требует аутентификацию через заголовок x-api-key и действующую API-квоту.

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
skip	number	0	Количество агентов для пропуска при пагинации (offset)	0
limit	number	10	Максимальное количество агентов на страницу (максимум 100)	20
sortBy	string	createdAt	Поле сортировки агентов (например, name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Направление сортировки (по возрастанию или убыванию)	desc
status	enum	optional	Фильтр по статусу агента (active или inactive)	active
executionMode	enum	optional	Фильтр по режиму выполнения (scheduled или batched)	scheduled
model	string	optional	Фильтр по названию LLM-модели	llama-2-70b-chat
search	string	optional	Полнотекстовый поиск по имени и промпту агента (без учёта регистра)	blog writer

Схема ответа (200 OK):

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Некорректные параметры запроса
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. Получить агента по ID

Endpoint: GET /agents/{agentId}

Кратко: Получить агента по ID

Описание: Возвращает полную конфигурацию и метаданные одного агента. Требует аутентификацию через заголовок x-api-key и действующую API-квоту.

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры пути:

Параметр	Тип	Описание	Пример
agentId	string	MongoDB ObjectId агента, который нужно получить	507f1f77bcf86cd799439011

Схема ответа (200 OK):

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID агента
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Агент или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. Список статей

Endpoint: GET /articles

Кратко: Получить список статей

Описание: Возвращает пагинированный список статей с расширенной фильтрацией по агенту, статусу, языку, тегам и полнотекстовым поиском по заголовку, описанию и ключевым словам. Требует аутентификацию через заголовок x-api-key и действующую API-квоту.

Аутентификация: Обязательна (x-api-key)

Теги: Articles

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
skip	number	0	Количество статей для пропуска при пагинации (offset)	0
limit	number	10	Максимальное количество статей на страницу (максимум 100)	20
sortBy	string	createdAt	Поле сортировки статей (например, title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Направление сортировки (по возрастанию или убыванию)	desc
agentId	string	optional	Фильтр по ID агента-источника статьи (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	optional	Фильтр по статусу публикации (draft, published, archived)	published
slug	string	optional	Фильтр статей по указанному slug	generic-article-slug-as-example
language	string	optional	Фильтр по языковому коду (например, en, tr, de)	en
model	string	optional	Фильтр по LLM-модели, использованной для генерации	llama-2-70b-chat
tags	string	optional	Фильтр по тегам (через запятую, совпадение с любым тегом)	featured,trending,tech
search	string	optional	Полнотекстовый поиск по заголовку, описанию, ключевым словам и тегам (без учёта регистра)	artificial intelligence

Схема ответа (200 OK):

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Некорректные параметры запроса
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. Получить статью по ID

Endpoint: GET /articles/{articleId}

Кратко: Получить статью по ID

Описание: Возвращает одну статью по её ID с полным содержимым и структурированными блоками. Требует аутентификацию через заголовок x-api-key и действующую API-квоту.

Аутентификация: Обязательна (x-api-key)

Теги: Articles

Параметры пути:

Параметр	Тип	Описание	Пример
articleId	string	MongoDB ObjectId статьи, которую нужно получить	607f1f77bcf86cd799439012

Схема ответа (200 OK):

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Типы блоков:

text: Обычный текстовый абзац

{"type": "text", "content": "Paragraph text"}

header: Заголовок (уровни 1–6)

{"type": "header", "content": "Heading", "level": 1}

image: Изображение с необязательной подписью

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list: Нумерованный или маркированный список
```
{"type": "list", "items": ["item1", "item2"], "ordered": false}
```

code: Блок кода с указанием языка

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video: Встраиваемое видео

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

Ответы с ошибками:

400 Bad Request: Неверный формат ID статьи
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Статья или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. Получить статьи агента

Endpoint: GET /agents/{agentId}/articles

Кратко: Получить статьи конкретного агента

Описание: Возвращает все статьи, созданные конкретным агентом, с фильтрацией и пагинацией. Статьи сортируются от новых к старым. Требует аутентификацию через заголовок x-api-key и действующую API-квоту.

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры пути:

Параметр	Тип	Описание	Пример
agentId	string	MongoDB ObjectId агента	507f1f77bcf86cd799439011

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
limit	number	50	Максимальное количество возвращаемых статей	30
skip	number	0	Количество записей для пропуска при пагинации	0
status	string	optional	Фильтр по статусу статьи (draft, published, archived)	published
sort	string	createdAt	Поле сортировки	createdAt
order	enum	desc	Направление сортировки (asc или desc)	desc
slug	string	optional	Фильтр статей по URL-friendly slug	getting-started-with-nextjs

Схема ответа (200 OK):

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID агента
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Агент или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. Получить данные рабочего пространства

Endpoint: GET /workspaces/{workspaceId}

Кратко: Получить данные рабочего пространства

Описание: Возвращает полные данные рабочего пространства, включая его метаданные, всех агентов и их опубликованные статьи с полным содержимым. Возвращает вложенную структуру агентов со статьями для удобного доступа к контенту рабочего пространства. Требует аутентификацию по API-ключу, соответствующему запрашиваемому workspace ID.

Аутентификация: Обязательна (x-api-key) — должна соответствовать запрашиваемому рабочему пространству

Теги: Workspaces

Параметры пути:

Параметр	Тип	Описание	Пример
workspaceId	string	MongoDB ObjectId рабочего пространства для получения	507f1f77bcf86cd799439010

Схема ответа (200 OK):

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID рабочего пространства
401 Unauthorized: Неверный API-ключ или несоответствие рабочего пространства
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

Обработка ошибок

Все эндпоинты возвращают стандартизированные ответы с ошибками и HTTP-статусами:

Формат ответа об ошибке

{
  "error": "Error type",
  "details": "Detailed error message"
}

HTTP-коды статуса

Статус	Описание
200	Успех — запрос успешно выполнен
400	Bad Request — некорректные параметры запроса или формат пути
401	Unauthorized — неверный или отсутствующий API-ключ
402	Payment Required — превышена квота API для тарифа рабочего пространства
404	Not Found — ресурс не существует
500	Internal Server Error — произошла ошибка на стороне сервера

Система квот

Каждое рабочее пространство имеет квоту API-вызовов в зависимости от тарифного плана. Квота сбрасывается ежемесячно и проверяется для каждого запроса.

Лимиты по тарифам

Free: 0 API-вызовов/месяц
Starter: 0 API-вызовов/месяц
Pro: 10,000 API-вызовов/месяц
Agency: ~ API-вызовов/месяц
Enterprise: Без ограничений

Применение квоты

Каждый API-запрос считается как 1 вызов в рамках месячной квоты. При превышении квоты:

HTTP Status: 402 Payment Required
Response: { error: "API access quota exceeded" }

Форматы ответов

Успешный ответ

Все успешные ответы возвращают статус 200 и JSON-данные:

{
  "data": [...],
  "pagination": {...}
}

Формат пагинации

Все list-эндпоинты используют единый формат метаданных пагинации:

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответ с ошибкой

Все ответы с ошибкой содержат поля error и details:

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

Сводка эндпоинтов

Метод	Endpoint	Описание
GET	/agents	Список агентов с пагинацией и фильтрами
GET	/agents/{agentId}	Получить одного агента по ID
GET	/articles	Список статей с пагинацией и расширенными фильтрами
GET	/articles/{articleId}	Получить одну статью по ID с полным содержимым
GET	/agents/{agentId}/articles	Получить статьи конкретного агента
GET	/workspaces/{workspaceId}	Получить рабочее пространство со всеми агентами и статьями
OPTIONS	/*	Поддержка CORS preflight

Документация API Inkpilots V1

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

Аутентификация по API-ключу

Все эндпоинты API V1 требуют аутентификации через API-ключ. API-ключ передаётся в заголовке запроса.

Формат заголовка:

x-api-key: Bearer <your-api-key>

Пример:

curl -H "x-api-key: Bearer your_api_key_here" https://inkpilots.com/api/v1/agents

Процесс проверки

Клиент отправляет запрос с заголовком x-api-key
Сервер вызывает функцию verifyApiKey(apiKeyHeader)
Если ключ валиден, возвращается:
- isValid: boolean
- workspaceId: string (MongoDB ObjectId в виде строки)
Если ключ невалиден, возвращается { isValid: false }

Ответы с ошибками

401 Unauthorized: Неверный или отсутствующий API-ключ, либо недостаточно прав
402 Payment Required: Превышена квота API-доступа для тарифа рабочего пространства

Базовый URL и CORS

Базовый URL

https://inkpilots.com/api/v1

Заголовки CORS

Все ответы включают следующие заголовки CORS:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, x-api-key

Примечание: CORS разрешает все источники, потому что API не использует cookie (stateless-аутентификация).

Preflight-запросы

Все эндпоинты поддерживают запросы OPTIONS для CORS preflight:

curl -X OPTIONS https://inkpilots.com/api/v1/agents

Ответ: 204 No Content с заголовками CORS.

Эндпоинты API

1. Список агентов

Endpoint: GET /agents

Кратко: Получить список агентов

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
skip	number	0	Количество агентов для пропуска при пагинации (offset)	0
limit	number	10	Максимальное количество агентов на страницу (максимум 100)	20
sortBy	string	createdAt	Поле сортировки агентов (например, name, createdAt, model, isActive)	createdAt
sortOrder	enum	desc	Направление сортировки (по возрастанию или убыванию)	desc
status	enum	optional	Фильтр по статусу агента (active или inactive)	active
executionMode	enum	optional	Фильтр по режиму выполнения (scheduled или batched)	scheduled
model	string	optional	Фильтр по названию LLM-модели	llama-2-70b-chat
search	string	optional	Полнотекстовый поиск по имени и промпту агента (без учёта регистра)	blog writer

Схема ответа (200 OK):

{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Blog Writer",
      "description": "Generates tech articles on a weekly schedule",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * MON",
      "model": "llama-2-70b-chat",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T15:45:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 12,
    "totalPages": 1,
    "currentPage": 1,
    "hasNextPage": false,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Некорректные параметры запроса
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents?limit=20&skip=0&status=active&sortBy=createdAt&sortOrder=desc&model=llama-2-70b-chat"

2. Получить агента по ID

Endpoint: GET /agents/{agentId}

Кратко: Получить агента по ID

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры пути:

Параметр	Тип	Описание	Пример
agentId	string	MongoDB ObjectId агента, который нужно получить	507f1f77bcf86cd799439011

Схема ответа (200 OK):

{
  "agent": {
    "id": "507f1f77bcf86cd799439011",
    "workspaceId": "507f1f77bcf86cd799439010",
    "name": "Tech Blog Writer",
    "description": "Generates tech articles on a weekly schedule",
    "status": "active",
    "executionMode": "scheduled",
    "schedule": "0 0 * * MON",
    "model": "llama-2-70b-chat",
    "language": "en",
    "prompt": "Write an article about: {topic}",
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-20T15:45:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID агента
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Агент или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011"

3. Список статей

Endpoint: GET /articles

Кратко: Получить список статей

Аутентификация: Обязательна (x-api-key)

Теги: Articles

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
skip	number	0	Количество статей для пропуска при пагинации (offset)	0
limit	number	10	Максимальное количество статей на страницу (максимум 100)	20
sortBy	string	createdAt	Поле сортировки статей (например, title, createdAt, status, updatedAt)	createdAt
sortOrder	enum	desc	Направление сортировки (по возрастанию или убыванию)	desc
agentId	string	optional	Фильтр по ID агента-источника статьи (MongoDB ObjectId)	507f1f77bcf86cd799439011
status	enum	optional	Фильтр по статусу публикации (draft, published, archived)	published
slug	string	optional	Фильтр статей по указанному slug	generic-article-slug-as-example
language	string	optional	Фильтр по языковому коду (например, en, tr, de)	en
model	string	optional	Фильтр по LLM-модели, использованной для генерации	llama-2-70b-chat
tags	string	optional	Фильтр по тегам (через запятую, совпадение с любым тегом)	featured,trending,tech
search	string	optional	Полнотекстовый поиск по заголовку, описанию, ключевым словам и тегам (без учёта регистра)	artificial intelligence

Схема ответа (200 OK):

{
  "data": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js 14",
      "slug": "getting-started-with-nextjs-14",
      "description": "Learn how to build modern web applications with Next.js 14",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdBy": "507f1f77bcf86cd799439050",
      "updatedBy": "507f1f77bcf86cd799439050",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Некорректные параметры запроса
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles?limit=25&skip=0&status=published&agentId=507f1f77bcf86cd799439011&language=en&tags=featured,trending&search=artificial+intelligence"

4. Получить статью по ID

Endpoint: GET /articles/{articleId}

Кратко: Получить статью по ID

Аутентификация: Обязательна (x-api-key)

Теги: Articles

Параметры пути:

Параметр	Тип	Описание	Пример
articleId	string	MongoDB ObjectId статьи, которую нужно получить	607f1f77bcf86cd799439012

Схема ответа (200 OK):

{
  "article": {
    "id": "607f1f77bcf86cd799439012",
    "workspaceId": "507f1f77bcf86cd799439010",
    "agentId": "507f1f77bcf86cd799439011",
    "title": "Getting Started with Next.js 14",
    "slug": "getting-started-with-nextjs-14",
    "description": "Learn how to build modern web applications with Next.js 14",
    "content": "Full article markdown/text content here...",
    "status": "published",
    "language": "en",
    "model": "llama-2-70b-chat",
    "tone": "professional",
    "tags": ["nextjs", "react", "web-development"],
    "blocks": [
      {
        "type": "header",
        "content": "Getting Started with Next.js 14",
        "level": 1
      },
      {
        "type": "text",
        "content": "Next.js 14 introduces new features..."
      },
      {
        "type": "image",
        "url": "https://example.com/image.jpg",
        "caption": "Next.js logo"
      }
    ],
    "meta": {
      "keywords": "nextjs, react, web development",
      "description": "Learn how to build modern web applications with Next.js 14",
      "tags": ["nextjs", "react", "web-development"]
    },
    "createdAt": "2024-01-10T08:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z",
    "createdBy": "507f1f77bcf86cd799439050",
    "updatedBy": "507f1f77bcf86cd799439050"
  }
}

Типы блоков:

text: Обычный текстовый абзац

{"type": "text", "content": "Paragraph text"}

header: Заголовок (уровни 1–6)

{"type": "header", "content": "Heading", "level": 1}

image: Изображение с необязательной подписью

{"type": "image", "url": "https://example.com/img.jpg", "caption": "Caption"}

list: Нумерованный или маркированный список
```
{"type": "list", "items": ["item1", "item2"], "ordered": false}
```

code: Блок кода с указанием языка

{"type": "code", "content": "const x = 1;", "language": "javascript"}

video: Встраиваемое видео

{"type": "video", "url": "https://example.com/video.mp4", "title": "Video title"}

Ответы с ошибками:

400 Bad Request: Неверный формат ID статьи
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Статья или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/articles/607f1f77bcf86cd799439012"

5. Получить статьи агента

Endpoint: GET /agents/{agentId}/articles

Кратко: Получить статьи конкретного агента

Аутентификация: Обязательна (x-api-key)

Теги: Agents

Параметры пути:

Параметр	Тип	Описание	Пример
agentId	string	MongoDB ObjectId агента	507f1f77bcf86cd799439011

Параметры запроса:

Параметр	Тип	По умолчанию	Описание	Пример
limit	number	50	Максимальное количество возвращаемых статей	30
skip	number	0	Количество записей для пропуска при пагинации	0
status	string	optional	Фильтр по статусу статьи (draft, published, archived)	published
sort	string	createdAt	Поле сортировки	createdAt
order	enum	desc	Направление сортировки (asc или desc)	desc
slug	string	optional	Фильтр статей по URL-friendly slug	getting-started-with-nextjs

Схема ответа (200 OK):

{
  "articles": [
    {
      "id": "607f1f77bcf86cd799439012",
      "workspaceId": "507f1f77bcf86cd799439010",
      "agentId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Next.js",
      "slug": "getting-started-with-nextjs",
      "description": "A comprehensive guide to Next.js",
      "status": "published",
      "language": "en",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "tags": ["nextjs", "react", "web-development"],
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "limit": 30,
    "totalCount": 45,
    "totalPages": 2,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID агента
401 Unauthorized: Неверный API-ключ
402 Payment Required: Превышена API-квота
404 Not Found: Агент или рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/agents/507f1f77bcf86cd799439011/articles?limit=30&skip=0&status=published&sort=createdAt&order=desc"

6. Получить данные рабочего пространства

Endpoint: GET /workspaces/{workspaceId}

Кратко: Получить данные рабочего пространства

Аутентификация: Обязательна (x-api-key) — должна соответствовать запрашиваемому рабочему пространству

Теги: Workspaces

Параметры пути:

Параметр	Тип	Описание	Пример
workspaceId	string	MongoDB ObjectId рабочего пространства для получения	507f1f77bcf86cd799439010

Схема ответа (200 OK):

{
  "workspace": {
    "id": "507f1f77bcf86cd799439010",
    "ownerId": "507f1f77bcf86cd799439001",
    "name": "My Content Studio",
    "description": "AI-powered content generation workspace",
    "plan": "pro",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-15T12:30:00Z"
  },
  "agents": [
    {
      "id": "607f1f77bcf86cd799439011",
      "workspaceId": "507f1f77bcf86cd799439010",
      "name": "Tech Content Agent",
      "description": "Generates technical articles and tutorials",
      "status": "active",
      "executionMode": "scheduled",
      "schedule": "0 0 * * *",
      "model": "llama-2-70b-chat",
      "tone": "professional",
      "language": "en",
      "isActive": true,
      "createdAt": "2024-01-10T12:00:00Z",
      "updatedAt": "2024-01-20T10:15:00Z",
      "articles": [
        {
          "id": "707f1f77bcf86cd799439012",
          "workspaceId": "507f1f77bcf86cd799439010",
          "agentId": "607f1f77bcf86cd799439011",
          "title": "Getting Started with Next.js",
          "slug": "getting-started-with-nextjs",
          "description": "A comprehensive guide to Next.js",
          "status": "published",
          "language": "en",
          "model": "llama-2-70b-chat",
          "tone": "professional",
          "tags": ["nextjs", "react", "web"],
          "createdAt": "2024-01-10T08:00:00Z",
          "updatedAt": "2024-01-15T12:30:00Z"
        }
      ]
    }
  ]
}

Ответы с ошибками:

400 Bad Request: Неверный формат ID рабочего пространства
401 Unauthorized: Неверный API-ключ или несоответствие рабочего пространства
402 Payment Required: Превышена API-квота
404 Not Found: Рабочее пространство не найдено
500 Internal Server Error: Ошибка сервера

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

curl -H "x-api-key: Bearer your_api_key" \
  "https://inkpilots.com/api/v1/workspaces/507f1f77bcf86cd799439010"

Обработка ошибок

Все эндпоинты возвращают стандартизированные ответы с ошибками и HTTP-статусами:

Формат ответа об ошибке

{
  "error": "Error type",
  "details": "Detailed error message"
}

HTTP-коды статуса

Статус	Описание
200	Успех — запрос успешно выполнен
400	Bad Request — некорректные параметры запроса или формат пути
401	Unauthorized — неверный или отсутствующий API-ключ
402	Payment Required — превышена квота API для тарифа рабочего пространства
404	Not Found — ресурс не существует
500	Internal Server Error — произошла ошибка на стороне сервера

Система квот

Лимиты по тарифам

Free: 0 API-вызовов/месяц
Starter: 0 API-вызовов/месяц
Pro: 10,000 API-вызовов/месяц
Agency: ~ API-вызовов/месяц
Enterprise: Без ограничений

Применение квоты

Каждый API-запрос считается как 1 вызов в рамках месячной квоты. При превышении квоты:

HTTP Status: 402 Payment Required
Response: { error: "API access quota exceeded" }

Форматы ответов

Успешный ответ

Все успешные ответы возвращают статус 200 и JSON-данные:

{
  "data": [...],
  "pagination": {...}
}

Формат пагинации

Все list-эндпоинты используют единый формат метаданных пагинации:

{
  "pagination": {
    "skip": 0,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3,
    "currentPage": 1,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Ответ с ошибкой

Все ответы с ошибкой содержат поля error и details:

{
  "error": "Unauthorized",
  "details": "Invalid or missing API key"
}

Сводка эндпоинтов

Метод	Endpoint	Описание
GET	/agents	Список агентов с пагинацией и фильтрами
GET	/agents/{agentId}	Получить одного агента по ID
GET	/articles	Список статей с пагинацией и расширенными фильтрами
GET	/articles/{articleId}	Получить одну статью по ID с полным содержимым
GET	/agents/{agentId}/articles	Получить статьи конкретного агента
GET	/workspaces/{workspaceId}	Получить рабочее пространство со всеми агентами и статьями
OPTIONS	/*	Поддержка CORS preflight

Документация API Inkpilots V1

Содержание

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

Аутентификация по API-ключу

Процесс проверки

Ответы с ошибками

Базовый URL и CORS

Базовый URL

Заголовки CORS

Preflight-запросы

Эндпоинты API

1. Список агентов

2. Получить агента по ID

3. Список статей

4. Получить статью по ID

5. Получить статьи агента

6. Получить данные рабочего пространства

Обработка ошибок

Формат ответа об ошибке

HTTP-коды статуса

Система квот

Лимиты по тарифам

Применение квоты

Форматы ответов

Успешный ответ

Формат пагинации

Ответ с ошибкой

Сводка эндпоинтов

Рекомендации

Пагинация

Фильтрация

Обработка ошибок

Производительность

Документация API Inkpilots V1

Содержание

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

Аутентификация по API-ключу

Процесс проверки

Ответы с ошибками

Базовый URL и CORS

Базовый URL

Заголовки CORS

Preflight-запросы

Эндпоинты API

1. Список агентов

2. Получить агента по ID

3. Список статей

4. Получить статью по ID

5. Получить статьи агента

6. Получить данные рабочего пространства

Обработка ошибок

Формат ответа об ошибке

HTTP-коды статуса

Система квот

Лимиты по тарифам

Применение квоты

Форматы ответов

Успешный ответ

Формат пагинации

Ответ с ошибкой

Сводка эндпоинтов

Рекомендации

Пагинация

Фильтрация

Обработка ошибок

Производительность