Справочник API (OpenAPI 3.1)

AskAIs Customer Service поставляется с полной спецификацией OpenAPI 3.1, описывающей каждую публичную конечную точку. Она лежит в основе наших автоматически генерируемых SDK и работает с любым инструментом экосистемы OpenAPI (Insomnia, Postman, Swagger UI, Hoppscotch и др.).

Получить спецификацию

# Live (cached 5 min, CORS open)
curl https://cs.askais.com/api/v1/openapi.json

# Save to disk
curl https://cs.askais.com/api/v1/openapi.json -o singlink-openapi.json

Базовый URL

• Облако: https://cs.askais.com/api/v1
• Самостоятельный хостинг: адрес, в который разрешается ваш APP_URL, с суффиксом /api/v1

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

Две схемы, обе через Authorization: Bearer <value>:

• JWT контакта — выдаётся через POST /auth/identify. Ограничен одним контактом. Используется web / мобильными SDK.
• API key рабочего пространства — sk_live_..., создаётся в Настройки → API Keys. Охватывает всё рабочее пространство. Для взаимодействия сервер-сервер.

Конечные точки кратко

• POST /auth/identify — выдать JWT контакта
• POST /conversations — начать новый чат
• GET /conversations — перечислить ваши
• GET /conversations/{id}
• GET /conversations/{id}/messages?before=&limit=
• POST /conversations/{id}/messages
• POST /upload — получить предподписанный S3 POST URL
• POST /upload/{id}/confirm

Ошибки

Все ответы, отличные от 2xx, используют стабильную оболочку:

{
  "error": {
    "code": "validation_error",
    "message": "content or attachments required",
    "field": "content"
  }
}

Коды: validation_error, unauthorized, forbidden, not_found, conflict, unprocessable, rate_limit_exceeded, internal_error.

Спутник реального времени

REST подходит для одиночных вызовов. Для живых сообщений подключитесь к wss://<wsUrl>/v1/ws?token=<jwt> и слушайте события message:new, ai:stream:delta, ai:stream:end, typing и presence. См. Веб-виджет для полной схемы событий.