Skip to Content
SDKs & ExamplescURL

cURL

cURL recipes for testing and automating VelaFlows API calls from the command line.

Authentication Setup

Set environment variables to avoid repeating credentials in every command:

export VELAFLOWS_TOKEN="sk_live_your_token_here"
export VELAFLOWS_WORKSPACE="your_workspace_id_here"
export VELAFLOWS_BASE="https://api.velaflows.com/api/v1"

All examples below assume these variables are set.

GET Requests

List Conversations

curl -s "$VELAFLOWS_BASE/inbox/conversations?page=1&limit=10" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq

Get a Specific Conversation

curl -s "$VELAFLOWS_BASE/inbox/conversations/65a1b2c3d4e5f6a7b8c9d0e1" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq '.data.conversation'

Filter Conversations by Channel

curl -s "$VELAFLOWS_BASE/inbox/conversations?channelType=whatsapp&status=open&limit=20" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq '.data.items | length'

List CRM Leads

curl -s "$VELAFLOWS_BASE/crm/leads?page=1&limit=20&sortBy=createdAt&sortOrder=desc" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq

List Tags

curl -s "$VELAFLOWS_BASE/tags?entityType=conversation" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq '.data.items[].name'

POST Requests

Create a CRM Lead

curl -s -X POST "$VELAFLOWS_BASE/crm/leads" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+1234567890",
    "pipelineId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "stageId": "65a1b2c3d4e5f6a7b8c9d0e2"
  }' | jq '.data.lead._id'

Send a Message

CONVERSATION_ID="65a1b2c3d4e5f6a7b8c9d0e1"
 
curl -s -X POST "$VELAFLOWS_BASE/inbox/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! How can I help you today?",
    "type": "text"
  }' | jq

Create a Tag

curl -s -X POST "$VELAFLOWS_BASE/tags" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customer",
    "color": "#FF6B35",
    "entityType": "conversation"
  }' | jq

Subscribe to Webhooks

curl -s -X POST "$VELAFLOWS_BASE/webhooks/subscriptions" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/velaflows",
    "events": ["conversation.created", "lead.stage_changed"],
    "secret": "your-webhook-secret"
  }' | jq

PATCH Requests

Update a Lead

LEAD_ID="65a1b2c3d4e5f6a7b8c9d0e1"
 
curl -s -X PATCH "$VELAFLOWS_BASE/crm/leads/$LEAD_ID" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "status": "qualified"
  }' | jq

Assign a Conversation

CONVERSATION_ID="65a1b2c3d4e5f6a7b8c9d0e1"
AGENT_ID="65a1b2c3d4e5f6a7b8c9d0e2"
 
curl -s -X PATCH "$VELAFLOWS_BASE/inbox/conversations/$CONVERSATION_ID/assign" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d "{\"agentId\": \"$AGENT_ID\"}" | jq

DELETE Requests

Delete a Tag

TAG_ID="65a1b2c3d4e5f6a7b8c9d0e1"
 
curl -s -X DELETE "$VELAFLOWS_BASE/tags/$TAG_ID" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" | jq

Tips and Tricks

Pretty-Print JSON with jq

Always pipe output through jq for readable JSON:

# Full response
curl -s ... | jq
 
# Extract specific field
curl -s ... | jq '.data.items[0].status'
 
# Count results
curl -s ... | jq '.data.pagination.total'
 
# Extract just names
curl -s ... | jq '.data.items[].firstName'

Save Response to File

curl -s "$VELAFLOWS_BASE/crm/leads?limit=100" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" \
  -o leads.json

Check Response Headers

Use -i to see response headers (including rate limit info):

curl -si "$VELAFLOWS_BASE/inbox/conversations" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE"

Look for these rate limit headers in the response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1711296000

Verbose Mode for Debugging

Use -v to see the full request and response for debugging:

curl -v "$VELAFLOWS_BASE/inbox/conversations" \
  -H "Authorization: Bearer $VELAFLOWS_TOKEN" \
  -H "x-workspace-id: $VELAFLOWS_WORKSPACE" 2>&1 | head -30

Create a Shell Function

Add this to your .bashrc or .zshrc for quick API access:

velaflows() {
  local method="${1:-GET}"
  local path="$2"
  local data="$3"
 
  local args=(-s -X "$method"
    "$VELAFLOWS_BASE$path"
    -H "Authorization: Bearer $VELAFLOWS_TOKEN"
    -H "x-workspace-id: $VELAFLOWS_WORKSPACE"
    -H "Content-Type: application/json"
  )
 
  if [ -n "$data" ]; then
    args+=(-d "$data")
  fi
 
  curl "${args[@]}" | jq
}
 
# Usage:
# velaflows GET "/inbox/conversations?limit=5"
# velaflows POST "/crm/leads" '{"firstName":"Jane","lastName":"Smith"}'
# velaflows PATCH "/crm/leads/ID" '{"status":"qualified"}'
# velaflows DELETE "/tags/ID"
PythonOverview