Overview

The Velaro REST API lets you create and update contacts, tag them, and search your Knowledge Base programmatically, for example from Make, Zapier, Power Automate, IFTTT, n8n, Pipedream, Workato or Activepieces.

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

Your plan sets four allowances: the number of API keys, the number of webhook endpoints, a per-minute call rate, and a daily call allowance. Higher plans include more of each. An admin or billing user can see the exact numbers for the account on Billing and on the API Keys page.

As usage approaches a limit, Velaro sends a warning by email to your account contacts and shows a notice on the API Keys page. When a limit is reached, requests return 429 Too Many Requests; the rate limit headers tell you when to retry. Make, Zapier, Power Automate, n8n and the other tools below all draw from this same allowance, with no separate connection fee. Contact support to discuss higher limits. Ask Moshky "how close am I to my API limits?" to see current usage against each allowance.

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:

Production:

https://api-admin-us-east.velaro.com/api/v1

Staging: https://velaro-admin-staging.azurewebsites.net/api/v1

Rate Limits

Rate limits depend on your plan: each plan includes a per-minute limit per key and a daily call allowance. An admin or billing user can see their exact numbers on Billing.

• 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

Endpoints

All paths are relative to the base URL above.

Example: Create or Update a Contact

curl -X POST https://api-admin-us-east.velaro.com/api/v1/contacts \
  -H "Authorization: Bearer vlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","firstName":"Jane","lastName":"Doe","company":"Acme","tags":["make-lead"]}'

Returns {"id":123,"created":true,"email":"jane@example.com","tags":["make-lead"]}. Fields you leave out are not changed on an existing contact.

Example: Tag a Contact

curl -X POST https://api-admin-us-east.velaro.com/api/v1/contacts/tag \
  -H "Authorization: Bearer vlk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","tag":"escalation-needed"}'

The tag is created if it does not exist. Tagging triggers any Email Campaign set to start on "Contact tag added".

Example: Search the Knowledge Base

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

Returns matching articles with id, title, description and url. Link visitors to the article URL.

Use It from Make, Zapier, Power Automate, IFTTT, n8n, Pipedream, Workato or Activepieces

• Make: HTTP → Make a request. See the Make Integration Guide.
• Zapier: Webhooks by Zapier → Custom Request, with the same URL, headers and JSON body.
• Power Automate: HTTP action with the same URL, headers and JSON body.
• IFTTT: Webhooks, Make a web request, with a JSON body. See the IFTTT Guide.
• n8n: HTTP Request node with Header Auth. See the n8n Guide.
• Pipedream: HTTP / Webhook, Send any HTTP Request. See the Pipedream Guide.
• Workato: HTTP connector, Make request. See the Workato Guide.
• Activepieces: HTTP piece, Send HTTP request. See the Activepieces Guide.
• Sending events out of Velaro: in a workflow, add the Make AI, Zapier, Power Automate or HTTP Request node (the HTTP Request node also works with IFTTT, n8n, Pipedream, Workato and Activepieces webhook URLs).

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

Webhook Subscriptions

Subscribe an https URL to events and Velaro posts each one to you as it happens. Supported events: contact_tag_added, conversation_started and conversation_closed.

Create a subscription with POST /webhooks and a body such as {"url":"https://example.com/hook","events":["contact_tag_added"]}. The response includes a signing secret that is shown once, so store it right away. Every delivery carries these headers: X-Velaro-Event, X-Velaro-Event-Id (use it to ignore a repeated delivery) and X-Velaro-Signature.

To verify a delivery, read t and v1 from X-Velaro-Signature (format t=<unix seconds>,v1=<hex>), compute HMAC-SHA256 over <t>.<raw body> using your secret, and compare it with v1. Reject anything where t is more than five minutes old. Failed deliveries are retried automatically.

Safe Retries

Send an Idempotency-Key header on POST /webhooks and POST /contacts/{id}/notes. Repeating a request with the same key within 24 hours returns the original result instead of creating a second one.

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