Quickstart

Prerequisites

A running Vela instance — self-host locally or use the cloud
A client secret (vela_cs_...) — to manage schemas and rules
An API key (vela_live_...) — to ingest events

Both credentials are generated from the dashboard. See the credentials guide.

Step 1: Install the SDK

npm install @vela-event/sdk

pnpm add @vela-event/sdk

pip install vela-sdk

Step 2: Set credentials as environment variables

Never hardcode credentials in your source files.

export VELA_CLIENT_SECRET="vela_cs_..."
export VELA_API_KEY="vela_live_..."

For local dev, put these in a .env file and load with dotenv.

Step 3: Register an event schema

Schemas tell Vela the exact shape of each event type. An event without a matching schema is rejected at ingest time with a 400 error.

import { VelaManagementClient } from '@vela-event/sdk';

const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);
const app = client.forApp('your-app-slug');

await app.schemas.create({
  eventName: 'order.placed',
  description: 'Fired when a customer completes checkout',
  fields: [
    { id: 'f1', name: 'orderId',      type: 'string', required: true  },
    { id: 'f2', name: 'amountCents',  type: 'number', required: true  },
    { id: 'f3', name: 'currency',     type: 'enum',   required: true,
      enumValues: ['USD', 'EUR', 'GBP'] },
    { id: 'f4', name: 'customerEmail',type: 'string', required: false },
  ],
});

console.log('Schema registered.');

import os
from vela import VelaManagementClient

client = VelaManagementClient(os.environ["VELA_CLIENT_SECRET"])
app = client.for_app("your-app-slug")

app.schemas.create({
    "event_name": "order.placed",
    "description": "Fired when a customer completes checkout",
    "fields": [
        {"id": "f1", "name": "orderId",       "type": "string", "required": True},
        {"id": "f2", "name": "amountCents",   "type": "number", "required": True},
        {"id": "f3", "name": "currency",      "type": "enum",   "required": True,
         "enum_values": ["USD", "EUR", "GBP"]},
        {"id": "f4", "name": "customerEmail", "type": "string", "required": False},
    ],
})

print("Schema registered.")

cat > vela/schemas/order.placed.json << 'EOF'
{
  "eventName": "order.placed",
  "description": "Fired when a customer completes checkout",
  "fields": [
    { "id": "f1", "name": "orderId",       "type": "string", "required": true },
    { "id": "f2", "name": "amountCents",   "type": "number", "required": true },
    { "id": "f3", "name": "currency",      "type": "enum",   "required": true,
      "enumValues": ["USD", "EUR", "GBP"] },
    { "id": "f4", "name": "customerEmail", "type": "string", "required": false }
  ]
}
EOF

vela push
# ✓ Created order.placed

Step 4: Send your first event

import { VelaIngestClient } from '@vela-event/sdk';

const ingest = new VelaIngestClient(process.env.VELA_API_KEY!);

const result = await ingest.ingest({
  event: 'order.placed',
  data: {
    orderId: 'ord_abc123',
    amountCents: 4999,
    currency: 'USD',
    customerEmail: 'jane@example.com',
  },
  level: 'info',
});

console.log(result.accepted);      // 1
console.log(result.events[0].id);  // evt_01j9...

import os
from vela import VelaIngestClient

with VelaIngestClient(os.environ["VELA_API_KEY"]) as ingest:
    result = ingest.ingest({
        "event": "order.placed",
        "data": {
            "orderId": "ord_abc123",
            "amountCents": 4999,
            "currency": "USD",
            "customerEmail": "jane@example.com",
        },
        "level": "info",
    })
    print(result.accepted)      # 1
    print(result.events[0].id)  # evt_01j9...

curl -X POST http://localhost:3000/v1/ingest \
  -H "x-api-key: vela_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.placed",
    "data": {
      "orderId": "ord_abc123",
      "amountCents": 4999,
      "currency": "USD"
    },
    "level": "info"
  }'

A successful ingest returns 201:

{
  "accepted": 1,
  "events": [
    { "id": "evt_01j9...", "eventName": "order.placed", "createdAt": "2024-06-01T12:00:00Z" }
  ]
}

If a required field is missing, you get 400:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Event validation failed: field 'amountCents' is required"
}

Step 5: Create a notification rule (optional)

Notification rules decide what events trigger alerts and where they go. Destinations (Slack, Discord, Email) are configured in the dashboard first — then referenced by ID in the rule.

await app.notificationRules.create({
  name: 'Alert on high-value orders',
  eventName: 'order.placed',
  conditions: [
    { field: 'amountCents', operator: 'gt', value: 10000 },
  ],
  actions: [
    {
      id: 'action-slack',
      destinationId: 'dest-uuid-from-dashboard',
      channel: 'slack',
      enabled: true,
    },
  ],
});

app.notification_rules.create({
    "name": "Alert on high-value orders",
    "event_name": "order.placed",
    "conditions": [
        {"field": "amountCents", "operator": "gt", "value": 10000},
    ],
    "actions": [
        {
            "id": "action-slack",
            "destination_id": "dest-uuid-from-dashboard",
            "channel": "slack",
            "enabled": True,
        },
    ],
})

Now every order.placed event with amountCents > 10000 will post a Slack message automatically — with retries and a dead-letter queue built in.

What’s next

Core Concepts

Understand apps, schemas, events, and rules in depth.

TypeScript SDK

Batch ingestion, error handling, all resource methods.

CLI

Manage schemas as code with diff, push, and pull.

API Reference

Direct HTTP API docs with request/response examples.

Getting Started

Credentials

Prerequisites

Step 1: Install the SDK

Step 2: Set credentials as environment variables

Step 3: Register an event schema

Step 4: Send your first event

Step 5: Create a notification rule (optional)

What’s next

Core Concepts

TypeScript SDK

CLI

API Reference

​Prerequisites

​Step 1: Install the SDK

​Step 2: Set credentials as environment variables

​Step 3: Register an event schema

​Step 4: Send your first event

​Step 5: Create a notification rule (optional)

​What’s next

Core Concepts

TypeScript SDK

CLI

API Reference

Prerequisites

Step 1: Install the SDK

Step 2: Set credentials as environment variables

Step 3: Register an event schema

Step 4: Send your first event

Step 5: Create a notification rule (optional)

What’s next