API Reference

Interactive reference for all 34 VelaFlows microservices. Each service exposes REST endpoints through the API gateway.

Base URL

All API requests go through the gateway:

https://api.velaflows.com/api/v1

For local development, the gateway runs on port 4000:

http://localhost:4000/api/v1

Authentication

Every authenticated request requires two headers:

Obtain tokens via the Auth API login endpoint, or create long-lived API tokens in Settings > API Tokens in the dashboard.

Response Format

Success Response

All successful responses follow this envelope:

{
  "success": true,
  "data": {
    "user": { "_id": "abc123", "email": "john@example.com" }
  }
}

Paginated Response

List endpoints return paginated results:

{
  "success": true,
  "data": {
    "items": [
      { "_id": "abc123", "name": "Item 1" },
      { "_id": "def456", "name": "Item 2" }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}

Query parameters for pagination:

Error Response

Errors return a structured error object:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": {
      "resourceId": "abc123"
    }
  }
}

Common error codes:

Validation Errors

When request validation fails (422), the details object contains field-level errors:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        { "path": "email", "message": "Invalid email address" },
        { "path": "password", "message": "Must be at least 8 characters" }
      ]
    }
  }
}

Rate Limits

Rate limiting is applied at the gateway level. Default limits:

When rate-limited, the response includes a 429 status code. Wait and retry after the window resets.

Services