Skip to Content
Getting StartedYour First API Call

Your First API Call

This guide walks you through making your first successful API request to VelaFlows. By the end, you’ll have listed your inbox conversations and understood the response format.

Step 1: Create an API Token

If you haven’t already, create an API token:

  1. Log in to app.velaflows.com 
  2. Go to Settings > Developer > API Tokens
  3. Click Create Token
  4. Name it “My First Token” and select the inbox:read scope
  5. Click Create and copy the token

Step 2: Find Your Workspace ID

Your workspace ID is visible in:

  • Settings > General in the dashboard
  • The URL bar when you’re on any dashboard page

It’s a 24-character string like 64f1a2b3c4d5e6f7a8b9c0d1.

Step 3: Make Your First Request

Let’s list conversations in your inbox. Choose your preferred language:

cURL

curl -X GET "https://api.velaflows.com/api/v1/inbox/conversations?page=1&limit=5" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const VELAFLOWS_TOKEN = 'sk_live_YOUR_TOKEN_HERE'
const WORKSPACE_ID = 'YOUR_WORKSPACE_ID'
 
const response = await fetch(
  'https://api.velaflows.com/api/v1/inbox/conversations?page=1&limit=5',
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${VELAFLOWS_TOKEN}`,
      'x-workspace-id': WORKSPACE_ID,
      'Content-Type': 'application/json',
    },
  }
)
 
const data = await response.json()
console.log(data)

Python (requests)

import requests
 
VELAFLOWS_TOKEN = "sk_live_YOUR_TOKEN_HERE"
WORKSPACE_ID = "YOUR_WORKSPACE_ID"
 
response = requests.get(
    "https://api.velaflows.com/api/v1/inbox/conversations",
    headers={
        "Authorization": f"Bearer {VELAFLOWS_TOKEN}",
        "x-workspace-id": WORKSPACE_ID,
        "Content-Type": "application/json",
    },
    params={"page": 1, "limit": 5},
)
 
data = response.json()
print(data)

Step 4: Understand the Response

A successful response looks like this:

{
  "success": true,
  "data": {
    "items": [
      {
        "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
        "workspaceId": "64f1a2b3c4d5e6f7a8b9c0d1",
        "channelType": "whatsapp",
        "status": "open",
        "priority": "normal",
        "assignedAgentId": "64f1a2b3c4d5e6f7a8b9c0d2",
        "lastMessageAt": "2026-03-24T10:30:00.000Z",
        "unreadCount": 2,
        "createdAt": "2026-03-20T08:15:00.000Z",
        "updatedAt": "2026-03-24T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 5,
      "total": 42,
      "totalPages": 9
    }
  }
}

Response Structure

All VelaFlows API responses follow a consistent format:

FieldTypeDescription
successbooleantrue if the request was successful
dataobjectThe response payload
data.itemsarrayList of resources (for paginated endpoints)
data.paginationobjectPagination metadata
data.pagination.pagenumberCurrent page number
data.pagination.limitnumberItems per page
data.pagination.totalnumberTotal items across all pages
data.pagination.totalPagesnumberTotal number of pages

For single-resource endpoints (e.g., get a specific conversation), the response uses a named key instead of items:

{
  "success": true,
  "data": {
    "conversation": { ... }
  }
}

Step 5: Handle Errors

If something goes wrong, the API returns an error response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Common Errors

StatusCodeMeaningFix
401UNAUTHORIZEDBad or missing tokenCheck your Authorization header
403FORBIDDENInsufficient permissionsCheck your token’s scopes
404NOT_FOUNDResource doesn’t existVerify the endpoint path and IDs
422VALIDATION_ERRORInvalid request bodyCheck the details.errors array
429TOO_MANY_REQUESTSRate limit exceededWait and retry (see Rate Limits)

What’s Next?

Now that you’ve made your first API call, explore more of the platform:

AuthenticationRate Limits & Errors