Velaro REST API Guide

Overview

The Velaro REST API lets you create conversations, manage contacts, and trigger automation workflows programmatically. API access is available on all plans.

The API is authenticated using API keys that you generate in the admin panel. Keys are scoped (read-only vs. read-write) and rate-limited per your plan.

Where to Find Your API Keys

To generate or manage your API keys:

1. Log in to the Velaro Admin panel at admin.velaro.com

2. Click Settings in the left sidebar

3. Under Developer, click API Keys

4. Click + Create API key, give it a name, and select the permissions (scopes) you need

5. Copy the key immediately — it is shown only once and cannot be retrieved later

Each key starts with vlk_ and is 52 characters total.

Authentication

Every API request must include your key in the Authorization header:

Authorization: Bearer vlk_your_api_key_here
Content-Type: application/json

Never include API keys in URLs or query strings — always use the header.

Base URL

All API endpoints are relative to:

https://api.velaro.com/v1

Rate Limits

Rate limits depend on your plan:

• Default: 60 requests per minute per key, 1,000 requests per day site-wide
• Higher tiers: Contact support to increase limits
• Rate limit headers are returned on every response: X-RateLimit-Remaining, X-RateLimit-Reset
• When you exceed the limit, you receive 429 Too Many Requests

Available Scopes

When creating an API key, select only the permissions your integration needs:

| Scope | What it allows |

|-------|---------------|

| read:conversations | List and retrieve conversations |

| write:conversations | Create new conversations |

| read:contacts | List and retrieve contacts |

| write:contacts | Create and update contacts |

How to Test Your API Key

The easiest way to test your API key is directly in the Velaro Admin:

1. Go to Settings → API Keys and create a key

2. Use the quick reference code snippet at the bottom of that page

3. Paste it into your terminal (requires curl) or Postman

For Postman:

• Method: GET
• URL: https://api.velaro.com/v1/conversations
• Header: Authorization: Bearer vlk_your_key

Example: List Conversations

curl https://api.velaro.com/v1/conversations \
  -H "Authorization: Bearer vlk_your_key"

Returns a paginated list of conversations for your site.

Example: Create a Conversation

curl -X POST https://api.velaro.com/v1/conversations \
  -H "Authorization: Bearer vlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorName": "Jane Doe",
    "visitorEmail": "jane@example.com",
    "channel": "web",
    "message": "Hi, I have a question about my order",
    "customData": {
      "orderId": "12345"
    }
  }'

Requires the write:conversations scope.

Key Management Best Practices

• One key per integration — create a separate key for each app or service that uses the API. This makes it easy to revoke access for a single integration without affecting others.
• Rotate keys regularly — use the Rotate button in Settings → API Keys. The old key is immediately revoked; the new key is shown once.
• Use read-only scopes by default — only add write:* scopes to keys that actually need to create or modify data.
• Never commit keys to version control — store them in environment variables or a secrets manager.

Revoking a Key

To revoke a key:

1. Go to Settings → API Keys in the admin panel

2. Find the key and click Revoke

3. Confirm — the key stops working immediately

Revoked keys cannot be restored. If you need to replace a key without downtime, use Rotate instead.

Errors

| Status | Meaning |

|--------|---------|

| 200 | Success |

| 400 | Bad request — check the request body |

| 401 | Unauthorized — key missing, invalid, or expired |

| 403 | Forbidden — key does not have the required scope |

| 429 | Rate limit exceeded — slow down or upgrade your plan |

| 500 | Server error — try again; contact support if persistent |

Webhooks vs. API Polling

If you need real-time notifications (e.g. trigger an external action when a conversation is resolved), use Webhooks instead of polling the API. Go to Settings → Webhooks to configure outbound event notifications.

Need Help?

• In the admin panel: Ask the Velaro AI assistant (bottom-right chat bubble) — it knows the platform
• Email: support@velaro.com
• API limits: If you need higher rate limits or additional scopes, contact support