Velaro REST API Guide

Last updated March 17, 2026 · 78 views

Velaro REST API Guide

Overview

The Velaro REST API lets you create conversations, manage contacts, search your Knowledge Base, and trigger automation workflows programmatically.

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

Plan Limits

Monthly call limits and key counts depend on your plan tier. Higher tiers unlock more keys, higher rate limits, and unlimited monthly calls.

| | Starter | Pro | Enterprise |

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

| Max active keys | 2 | 5 | Unlimited |

| Monthly call limit | 1,000 | 10,000 | Unlimited |

| Rate limit (per key) | 30 req/min | 60 req/min | 300 req/min |

| Available scopes | All | All | All |

When your monthly call limit is reached, requests return 429 Too Many Requests with a X-RateLimit-Remaining-Month: 0 header. Limits reset on the 1st of each month at 00:00 UTC. Contact support to discuss higher limits or custom quotas.

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:

  • Pro: 60 requests per minute per key, 10,000 requests per month site-wide
  • Enterprise: 300 requests per minute per key, unlimited monthly
  • 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 |

| read:kb | Search and retrieve published Knowledge Base articles |

Knowledge Base API

If your plan includes the Knowledge Base feature, the read:kb scope lets external apps search your published help articles.

Search KB Articles

curl "https://api.velaro.com/v1/kb/search?q=password+reset&limit=5" \
  -H "Authorization: Bearer vlk_your_key"

Returns:

{
  "q": "password reset",
  "count": 3,
  "articles": [
    {
      "id": 42,
      "title": "How to Reset Your Password",
      "description": "Step-by-step guide to resetting your account password.",
      "url": "https://help.velaro.com/kb/article/42/how-to-reset-your-password",
      "topic": "Account Settings",
      "category": "Getting Started",
      "tags": "password, login, account"
    }
  ]
}

Get a Single KB Article

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

Returns article metadata (title, description, URL). The full HTML content is not returned via API — link visitors to the article URL instead.

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.
  • Monitor your usage — the API Keys page shows monthly usage vs. your plan limit. Set up an alert before you hit the cap.

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, or API access is not available on your plan |

| 429 | Rate limit exceeded — slow down, or your monthly limit was reached; upgrade your plan for higher limits |

| 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
  • Higher limits or custom quotas: contact support — we can accommodate high-volume use cases

Was this article helpful?