Deploy and Host Evolution API — Lite Version on Railway

Evolution API — Lite Version is a lightweight, API-only Evolution API deployment template for Railway. It runs Evolution API Lite with PostgreSQL and persistent volume storage, giving you a simple WhatsApp HTTP REST API backend without Redis and without the Manager UI. Use REST API endpoints directly to create instances, scan QR codes, check connection status, and send WhatsApp messages.

Imgur

About Hosting Evolution API — Lite Version

Hosting Evolution API — Lite Version on Railway gives you a smaller and simpler Evolution API stack. This template is designed for users who want the lightest practical setup while still keeping PostgreSQL for database persistence and a mounted volume for instance/session files. Railway handles deployment, public domain setup, environment variables, networking, storage, and service management. Unlike the full Evolution API template, this Lite Version does not include the /manager dashboard. All instance management is done through REST API calls such as creating an instance, connecting WhatsApp with QR code, checking instance status, listing instances, and sending messages.

Common Use Cases

Running a lightweight WhatsApp HTTP REST API backend
Sending WhatsApp alerts, notifications, and automation messages
Building custom WhatsApp integrations using REST API calls

Dependencies for Evolution API — Lite Version Hosting

PostgreSQL database
Railway volume for persistent instance storage

Deployment Dependencies

Implementation Details

This template uses the Evolution API Lite Docker image:

atendai/evolution-api-lite

Recommended environment variables:

PORT=8080
SERVER_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=${{Postgres.DATABASE_URL}}
AUTHENTICATION_API_KEY=${{secret(64, "abcdef0123456789")}}

This template does not include Redis and does not include the Evolution API Manager UI.

If you open:

https://YOUR-EVOLUTION-LITE-URL/manager

and see:

{
  "status": 404,
  "error": "Not Found",
  "response": {
    "message": ["Cannot GET /manager"]
  }
}

that is expected for the Lite Version. Use REST API endpoints directly instead.

Persistent Volume Configuration

Use a Railway volume to persist instance-related files.

Recommended volume configuration:

Mount Path: /evolution/instances
Initial Size: 5.00 GB
Resize: Live resize supported

The volume is mounted to:

/evolution/instances

This is useful because Evolution API may store instance/session-related files in this directory. By using a persistent volume, the data can remain available even when the service is redeployed or restarted.

How to Use Evolution API — Lite Version

Prepare these values first:

BASE_URL=https://YOUR-EVOLUTION-LITE-URL
API_KEY=YOUR_AUTHENTICATION_API_KEY
INSTANCE=main

You can find the API key in Railway:

Railway -> evolution-api-lite service -> Variables -> AUTHENTICATION_API_KEY

Use your Railway public URL as BASE_URL.

1. Check That the API Is Running

Open your public URL in the browser:

https://YOUR-EVOLUTION-LITE-URL

Or use curl:

curl "https://YOUR-EVOLUTION-LITE-URL"

Do not use /manager because this Lite Version does not include the Manager UI.

2. Create a WhatsApp Instance

Create a new instance named main.

curl -X POST "https://YOUR-EVOLUTION-LITE-URL/instance/create" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY" \
  -d '{
    "instanceName": "main",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'

PowerShell one-line version:

curl.exe -X POST "https://YOUR-EVOLUTION-LITE-URL/instance/create" -H "Content-Type: application/json" -H "apikey: YOUR_AUTHENTICATION_API_KEY" -d "{\"instanceName\":\"main\",\"qrcode\":true,\"integration\":\"WHATSAPP-BAILEYS\"}"

Optional: Create an Instance With a Phone Number

You can also include the phone number in international format without the + symbol:

curl -X POST "https://YOUR-EVOLUTION-LITE-URL/instance/create" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY" \
  -d '{
    "instanceName": "main",
    "number": "6281234567890",
    "qrcode": true,
    "integration": "WHATSAPP-BAILEYS"
  }'

Correct number format:

6281234567890

Incorrect number format:

+6281234567890
081234567890

3. Get QR Code / Connect Instance

If the create request does not return a QR code, call the connect endpoint:

curl -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/connect/main" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY"

PowerShell one-line version:

curl.exe -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/connect/main" -H "apikey: YOUR_AUTHENTICATION_API_KEY"

The response may include a QR value, QR code string, or base64 QR image depending on the version. Scan it using WhatsApp:

WhatsApp -> Linked devices -> Link a device -> Scan QR code

Wait until the instance is connected.

4. List All Instances

Use this endpoint to list existing instances:

curl -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/fetchInstances" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY"

PowerShell one-line version:

curl.exe -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/fetchInstances" -H "apikey: YOUR_AUTHENTICATION_API_KEY"

5. Check Instance Connection Status

Check the connection state for the main instance:

curl -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/connectionState/main" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY"

PowerShell one-line version:

curl.exe -X GET "https://YOUR-EVOLUTION-LITE-URL/instance/connectionState/main" -H "apikey: YOUR_AUTHENTICATION_API_KEY"

If the instance is connected, the response should show a connected/open state depending on the API version.

6. Send a Test WhatsApp Message

After the instance is connected, send a test message:

curl -X POST "https://YOUR-EVOLUTION-LITE-URL/message/sendText/main" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY" \
  -d '{
    "number": "6281234567890",
    "text": "Hello from Evolution API Lite!"
  }'

PowerShell one-line version:

curl.exe -X POST "https://YOUR-EVOLUTION-LITE-URL/message/sendText/main" -H "Content-Type: application/json" -H "apikey: YOUR_AUTHENTICATION_API_KEY" -d "{\"number\":\"6281234567890\",\"text\":\"Hello from Evolution API Lite!\"}"

If the message is received, your Evolution API Lite setup is working.

7. Optional: Restart Instance

If the instance needs to be restarted:

curl -X PUT "https://YOUR-EVOLUTION-LITE-URL/instance/restart/main" \
  -H "apikey: YOUR_AUTHENTICATION_API_KEY"

PowerShell one-line version:

curl.exe -X PUT "https://YOUR-EVOLUTION-LITE-URL/instance/restart/main" -H "apikey: YOUR_AUTHENTICATION_API_KEY"

Troubleshooting

Unauthorized

If you see:

{
  "status": 401,
  "error": "Unauthorized",
  "response": {
    "message": "Unauthorized"
  }
}

check the following:

1. Make sure AUTHENTICATION_API_KEY exists in Railway Variables.
2. Redeploy the Evolution API Lite service after changing variables.
3. Use the header name exactly as: apikey
4. Do not use Authorization: Bearer.
5. Remove extra spaces before or after the API key.
6. In Railway UI, do not wrap the variable value in extra quotes.

curl: URL rejected / -H command not found

This usually happens because the multiline curl format is used in the wrong terminal.

Use the PowerShell one-line examples on Windows PowerShell.

Use the multiline examples with \ only on Linux, macOS, or Git Bash.

Manager Not Found

This Lite Version does not include Manager UI. Cannot GET /manager is expected. Use REST API endpoints directly.

More Endpoints

For more endpoints and request examples, use the Evolution API Postman collection:

https://www.postman.com/agenciadgcode/evolution-api/request/p52k6fp/create-instance

The Postman collection includes more examples for instance management, connection, messaging, and other Evolution API endpoints.

Why Deploy Evolution API — Lite Version on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Evolution API — Lite Version on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.