REST API Reference

Manage conversations, messages, knowledge base, and analytics programmatically with the Yanıtly REST API.

Overview

Base URL

https://api.yanitly.com/v1

Format

JSON (application/json)

Rate Limit

100 req/min (Starter), 500 req/min (Enterprise)

Versioning

URL-based (/v1/)

Authentication

JWT Bearer token is used for API requests. Send the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Authentication

POST /v1/auth/login

Log in with email and password. Returns JWT access and refresh tokens. If 2FA is active, returns requiresTwoFactor: true first — then resend with totpCode.

Request Body

{
  "email": "user\u0040example.com",
  "password": "your_password",
  "totpCode": "123456"  // 2FA aktifse gerekli (opsiyonel)
}

Response (200)

// ── Normal Giriş (2FA kapalı) ──
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user\u0040example.com",
    "role": "tenant_admin"
  }
}

// ── 2FA Aktif — İlk Adım (totpCode gönderilmediğinde) ──
{
  "requiresTwoFactor": true,
  "email": "user\u0040example.com"
}
// → Kullanıcıdan 6 haneli TOTP kodunu alıp
//   aynı endpoint'e email + password + totpCode
//   ile tekrar istek gönderin.

POST /v1/auth/refresh

Get a new access token using a refresh token.

Request Body

{ "refreshToken": "eyJhbGciOiJIUzI1NiIs..." }

POST /v1/auth/register

Create a new user and tenant registration.

Request Body

{
  "email": "user\u0040example.com",
  "password": "strong_password",
  "name": "Ahmet Yılmaz",
  "companyName": "Acme Inc."
}

Conversations

GET /v1/conversations

Returns the list of conversations for the tenant. Supports pagination, filtering, and sorting.

Response (200)

{
  "data": [
    {
      "id": "conv_abc123",
      "channel": "whatsapp",
      "status": "active",
      "lastMessage": "Siparişim nerede?",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": { "total": 42, "page": 1, "limit": 20 }
}

GET /v1/conversations/:id

Returns details and message history of a specific conversation.

PATCH /v1/conversations/:id

Update conversation status (active, resolved, archived).

Request Body

{ "status": "resolved" }

POST /v1/conversations/:id/assign

Assign conversation to an operator.

Request Body

{ "operatorId": "user_uuid" }

Messages

POST /v1/messages

Send a message to a conversation.

Request Body

{
  "conversationId": "conv_abc123",
  "content": "Siparişiniz kargoya verildi!",
  "type": "text"
}

GET /v1/conversations/:id/messages

Get message history in a conversation.

Knowledge Base

GET /v1/knowledge

List knowledge base contents.

POST /v1/knowledge

Add new content to the knowledge base.

Request Body

{
  "title": "İade Politikası",
  "content": "Ürünler 14 gün içinde...",
  "category": "Politikalar"
}

DELETE /v1/knowledge/:id

Delete content from the knowledge base.

Channels

GET /v1/channels

List connected channels.

POST /v1/channels

Create a new channel connection and save its configuration.

Analytics

GET /v1/analytics/overview

Get overall analytics data (conversation count, average response time, satisfaction score).

Response (200)

{
  "totalConversations": 1250,
  "avgResponseTime": 12.5,
  "satisfactionScore": 4.6,
  "aiResolutionRate": 78.3,
  "period": "last_30_days"
}

GET /v1/analytics/conversations

Get conversation analytics (date-based distribution).

Webhooks

GET /v1/webhooks

List registered webhooks.

POST /v1/webhooks

Create a new webhook registration.

Request Body

{
  "url": "https://yourapp.com/webhooks/yanitly",
  "events": ["conversation.created", "message.received"],
  "secret": "your_webhook_secret"
}

Error Codes

400 Bad Request — Invalid request format

401 Unauthorized — Invalid or missing token

403 Forbidden — You don't have permission for this action

404 Not Found — Resource not found

409 Conflict — Resource already exists

429 Too Many Requests — Rate limit exceeded

500 Internal Server Error — Server error

Related Resources