> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/EvolutionAPI/evolution-api/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Learn about the Evolution API architecture, base configuration, and available endpoints

Evolution API is a production-ready, multi-tenant WhatsApp API platform built with Node.js, TypeScript, and Express.js. The API follows RESTful principles and provides comprehensive endpoints for managing WhatsApp instances and interactions.

## REST Architecture

Evolution API is built on a RESTful architecture with the following characteristics:

* **Stateless operations**: Each request contains all information needed for processing
* **Resource-based URLs**: Endpoints represent resources (instances, messages, chats, etc.)
* **Standard HTTP methods**: Uses POST, GET, PUT, and DELETE appropriately
* **JSON payloads**: All request and response bodies use JSON format
* **HTTP status codes**: Returns semantic status codes (200, 201, 400, 401, 404, 500)

## Base URL Configuration

Configure your Evolution API base URL using the `SERVER_URL` environment variable:

```bash theme={null}
SERVER_URL=https://api.yourdomain.com
```

The server configuration is defined in `src/config/env.config.ts:39` and includes:

<ParamField path="SERVER.URL" type="string" required>
  The base URL where your Evolution API is accessible
</ParamField>

<ParamField path="SERVER.PORT" type="number" default="8080">
  The port on which the API server listens
</ParamField>

<ParamField path="SERVER.TYPE" type="string" default="http">
  Server protocol type: `http` or `https`
</ParamField>

### Making Your First Request

All requests to Evolution API follow this pattern:

```bash theme={null}
POST {SERVER_URL}/endpoint
Content-Type: application/json
apikey: YOUR_API_KEY
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.yourdomain.com/ \
    -H "apikey: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.yourdomain.com/', {
    method: 'GET',
    headers: {
      'apikey': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.yourdomain.com/',
      headers={
          'apikey': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
      }
  )

  print(response.json())
  ```
</CodeGroup>

## API Versioning

Evolution API currently uses implicit versioning through the package version. The API version is included in root endpoint responses:

```json theme={null}
{
  "status": 200,
  "message": "Welcome to the Evolution API, it is working!",
  "version": "2.1.0",
  "documentation": "https://doc.evolution-api.com"
}
```

<Note>
  Future versions may introduce explicit URL-based versioning (e.g., `/v2/instance/create`). Monitor the changelog for updates.
</Note>

## Endpoint Categories

Evolution API organizes endpoints into logical categories. Each category is defined in `src/api/routes/index.router.ts`:

### Instance Management

Manage WhatsApp instances with full lifecycle control.

* **Base Path**: `/instance`
* **Router**: `src/api/routes/instance.router.ts`
* **Operations**: Create, connect, disconnect, restart, delete instances

### Message Operations

Send various types of WhatsApp messages.

* **Base Path**: `/message`
* **Router**: `src/api/routes/sendMessage.router.ts`
* **Message Types**: Text, media, audio, location, contact, reaction, poll, list, buttons, stickers

### Chat Management

Manage WhatsApp conversations and chat metadata.

* **Base Path**: `/chat`
* **Router**: `src/api/routes/chat.router.ts`
* **Operations**: Find chats, archive, delete, mark as read/unread, fetch messages

### Group Operations

Manage WhatsApp groups and participants.

* **Base Path**: `/group`
* **Router**: `src/api/routes/group.router.ts`
* **Operations**: Create groups, manage participants, update settings, fetch group info

### Business Profile

Manage WhatsApp Business profile information.

* **Base Path**: `/business`
* **Router**: `src/api/routes/business.router.ts`
* **Operations**: Update profile, fetch business info

### Call Management

Handle WhatsApp call events and actions.

* **Base Path**: `/call`
* **Router**: `src/api/routes/call.router.ts`
* **Operations**: Reject calls, fetch call history

### Labels

Manage WhatsApp message labels for organization.

* **Base Path**: `/label`
* **Router**: `src/api/routes/label.router.ts`
* **Operations**: Create, update, delete labels

### Templates

Manage WhatsApp Business message templates.

* **Base Path**: `/template`
* **Router**: `src/api/routes/template.router.ts`
* **Operations**: Create, update, fetch templates

### Settings

Configure instance-specific settings.

* **Base Path**: `/settings`
* **Router**: `src/api/routes/settings.router.ts`
* **Operations**: Update instance settings, fetch configuration

### Proxy Configuration

Manage proxy settings for instances.

* **Base Path**: `/proxy`
* **Router**: `src/api/routes/proxy.router.ts`
* **Operations**: Configure proxy, remove proxy settings

### Integrations

Evolution API supports multiple integration categories:

* **Channels**: WhatsApp providers (Baileys, Business API, Evolution)
* **Chatbots**: AI integrations (OpenAI, Dify, Typebot, Chatwoot, N8N)
* **Events**: Event systems (WebSocket, RabbitMQ, SQS, NATS, Kafka, Pusher)
* **Storage**: File storage (S3, MinIO)

<Accordion title="View All Integration Endpoints">
  Integration endpoints are mounted directly on the root path:

  * **Channel Router**: Manages WhatsApp provider integrations
  * **Event Router**: Configures webhook and event delivery
  * **Chatbot Router**: Connects AI and automation platforms
  * **Storage Router**: Configures cloud storage for media

  See the respective integration documentation for detailed endpoint information.
</Accordion>

## Request/Response Flow

Evolution API follows a consistent request/response pattern:

### Successful Request Example

<CodeGroup>
  ```bash Request theme={null}
  POST https://api.yourdomain.com/instance/create
  Content-Type: application/json
  apikey: YOUR_GLOBAL_API_KEY

  {
    "instanceName": "my-instance",
    "token": "my-instance-token",
    "qrcode": true
  }
  ```

  ```json Response (201 Created) theme={null}
  {
    "instance": {
      "instanceName": "my-instance",
      "status": "created"
    },
    "hash": {
      "apikey": "my-instance-token"
    },
    "qrcode": {
      "code": "2@...",
      "base64": "data:image/png;base64,..."
    }
  }
  ```
</CodeGroup>

### Error Request Example

<CodeGroup>
  ```bash Request theme={null}
  GET https://api.yourdomain.com/instance/connectionState/nonexistent
  Content-Type: application/json
  apikey: INVALID_KEY
  ```

  ```json Response (401 Unauthorized) theme={null}
  {
    "status": 401,
    "error": "Unauthorized",
    "message": "Unauthorized"
  }
  ```
</CodeGroup>

## Multi-Tenant Architecture

Evolution API is built for multi-tenancy with complete data isolation:

<Warning>
  **Critical**: All operations must be scoped by `instanceName` or `instanceId`. Cross-tenant data access is prevented at the database and application layers.
</Warning>

### Instance Isolation

Each instance represents a separate WhatsApp connection with:

* **Isolated authentication**: Per-instance API keys (tokens)
* **Separate data**: Messages, chats, and contacts are instance-specific
* **Independent configuration**: Settings, webhooks, and integrations per instance
* **Resource boundaries**: Memory and connection management per instance

### URL Pattern for Instance Operations

Most endpoints follow this pattern:

```
/endpoint/:instanceName
```

Example:

```bash theme={null}
GET /chat/findChats/my-instance
```

The `instanceName` parameter is extracted from the URL path and validated before processing (`src/api/abstract/abstract.router.ts:34`).

## Rate Limiting

<Note>
  Evolution API does not currently implement built-in rate limiting at the application level. You should implement rate limiting at the infrastructure level using:

  * **Reverse proxy**: Nginx, Apache, or Traefik with rate limit modules
  * **API Gateway**: AWS API Gateway, Kong, or similar solutions
  * **Load balancer**: CloudFlare, AWS ALB with rate limiting rules
</Note>

### Recommended Rate Limits

For WhatsApp API compliance and stability:

* **Message sending**: 80 messages per second per instance (WhatsApp limit)
* **API requests**: 100 requests per second per client
* **Instance creation**: 10 instances per minute per API key
* **Webhook retries**: Exponential backoff with max 5 attempts

## CORS Configuration

Configure Cross-Origin Resource Sharing (CORS) via environment variables:

```bash theme={null}
CORS_ORIGIN=https://app.yourdomain.com,https://admin.yourdomain.com
CORS_METHODS=POST,GET,PUT,DELETE
CORS_CREDENTIALS=true
```

The CORS configuration is defined in `src/config/env.config.ts` and applied at the Express application level.

## Health Check Endpoint

Use the root endpoint for health checks:

```bash theme={null}
GET /
```

**Response:**

```json theme={null}
{
  "status": 200,
  "message": "Welcome to the Evolution API, it is working!",
  "version": "2.1.0",
  "clientName": "your-client",
  "manager": "https://api.yourdomain.com/manager",
  "documentation": "https://doc.evolution-api.com",
  "whatsappWebVersion": "2.2412.54"
}
```

<Note>
  No authentication is required for the health check endpoint.
</Note>

## Metrics and Monitoring

Evolution API supports Prometheus metrics when enabled:

```bash theme={null}
PROMETHEUS_METRICS=true
METRICS_ALLOWED_IPS=127.0.0.1,10.0.0.0/8
METRICS_AUTH_REQUIRED=true
METRICS_USER=admin
METRICS_PASSWORD=secure-password
```

**Metrics Endpoint:**

```bash theme={null}
GET /metrics
Authorization: Basic base64(user:password)
```

Available metrics (defined in `src/api/routes/index.router.ts:106-160`):

* `evolution_environment_info`: Environment and version information
* `evolution_instances_total`: Total number of active instances
* `evolution_instance_up`: Instance connection status (1 = connected, 0 = disconnected)
* `evolution_instance_state`: Detailed instance state with labels

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/api/errors">
    Understand error codes and troubleshooting
  </Card>

  <Card title="Instance Management" icon="server" href="/api/instance/create">
    Create and manage WhatsApp instances
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/api/messages/send-text">
    Send messages, media, and interactive content
  </Card>
</CardGroup>