# How to Use ConnectiveOne API

ConnectiveOne provides REST API for receiving and changing data, launching scenarios, and integrating with external systems. This article explains the basics of working with API. For a complete list of endpoints and details, see [API reference](/en/integrations/reference/api-reference.md).

---

## What Can You Do Through API?

- Get data about dialogues, operators, users, tickets
- Change dialogue parameters (status, topic, comment)
- Launch bot scenarios
- Manage data through Custom Data API
- Get statistics and analytics

---

## Access to API Documentation

To view all available endpoints:

1. Open the **help menu** (help icon in the upper right corner)
2. Select **"API Documentation"**

Swagger UI opens with complete documentation and the ability to test endpoints.

> 💡 **Tip:** Swagger UI allows not only viewing documentation but also testing API endpoints directly in the interface.

---

## Authorization

Authorization is required to make API requests. ConnectiveOne supports two types of authorization:

### API Key (Simplified Authorization)

Used for simple requests. The API key can be obtained in **Settings → Bot List → Bot Settings**.

**Header format:**
```http
Authorization: API-Key YOUR_API_KEY
```

**Example curl:**
```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/general/KwBots/get \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### JWT Token (Full Authorization)

For enterprise clients, JWT token authorization is available, which includes token refresh functions, expiration setting, and request rate limiting.

**Header format:**
```http
Authorization: Bearer YOUR_JWT_TOKEN
```

**Obtaining JWT token:**
Use the `/api/v1/auth/login` endpoint to obtain a JWT token.

---

## Main Request Types

### GET (Receiving Data)

Used to receive data from ConnectiveOne.

**Format:**
```
GET https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/get
```

**Example:**
```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/get \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### POST (Creating/Updating)

Used to create or update data.

**Format:**
```
POST https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/set
```

**Example:**
```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/set \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "chatroom_id": 123
  }'
```

---

## Response Format

**Successful response:**
```json
{
  "status": "success",
  "data": [...]
}
```

**Error:**
```json
{
  "status": "error",
  "message": "Error description"
}
```

---

## Usage Examples

### Example 1: Getting Dialogue List

```bash
curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/v1/OpChatRooms/list \
  -H "Authorization: API-Key YOUR_API_KEY"
```

### Example 2: Changing Dialogue Status

```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'
```

### Example 3: Changing Dialogue Topic and Status

```bash
curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": 5,
    "status": "processed",
    "kw_chat_title": "New Title",
    "comment": "Updated via API"
  }'
```

---

## Available Modules

### General Module
- Bot list
- Registered clients

### Operator Panel Module
- Dialogues through operator panels
- Operators
- Topics (subject areas) in operator panels
- Quick replies
- Skill groups

### Custom Data Module
- All data from custom modules

### API for Launching Scenarios
- `call_node` - launch scenario via API
- Entry Point URLs - direct links for launching

---

## Security and Limitations

### Security
- Use HTTPS for all requests
- Keep API keys and tokens in a secure place
- Do not share keys in public places or logs
- You can configure an IP address list to limit access
- Data is stored according to ISO 27001 standard

### Limitations
- API module is available for enterprise users
- Authorization is required for all requests
- Rate limiting may be applied depending on the tariff plan
- Maximum data size is limited by system settings

---

## Where to Find Complete Documentation?

1. **Swagger UI in system** — help menu → API Documentation (`/api-docs`)
2. **API reference** — [complete list of endpoints](/en/integrations/reference/api-reference.md)

---

## Related Articles

- [API reference](/en/integrations/reference/api-reference.md) — complete list of endpoints and parameters
- [Launch scenario via API call_node](/en/integrations/how-to/launch-scenario-via-call-node.md)
- [What are integrations](/en/integrations/explanation/what-are-integrations.md) — overview of integration types