Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velahq.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
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.');

​
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...
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,
    },
  ],
});
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.