API Documentation
Sending events
Sending events to Vayu
Vayu processes events in batches. If some events in a batch are invalid, only those are discarded — valid events are still ingested.
Event structure
Each event requires four fields:
| Field | Type | Description |
|---|---|---|
name | string | Event label (e.g. api_call, storage_used) |
timestamp | ISO 8601 datetime | When the event occurred (UTC) |
customerAlias | string | Identifies the customer (external ID or alias) |
ref | string | Unique reference for idempotency |
data | object (optional) | Arbitrary key-value metadata |
Batch limits
- Minimum events: 1
- Maximum events: 1,000
- Total payload size: 256 KB
Example
import { Vayu } from 'vayu-ts';
const vayu = new Vayu(process.env.VAYU_API_KEY);
const result = await vayu.events.send([
{
name: 'api_call',
timestamp: new Date(),
customerAlias: 'customer-123',
ref: 'evt_abc123',
data: { endpoint: '/users', method: 'GET' },
},
]);
console.log('Valid:', result.validEvents.length);
console.log('Invalid:', result.invalidEvents.length);from vayu_sdk import Vayu
from datetime import datetime, timezone
import os
vayu = Vayu(api_key=os.environ["VAYU_API_KEY"])
result = vayu.events.send(events=[
{
"name": "api_call",
"timestamp": datetime.now(timezone.utc),
"customerAlias": "customer-123",
"ref": "evt_abc123",
"data": {"endpoint": "/users", "method": "GET"},
},
])
print("Valid:", len(result.valid_events))
print("Invalid:", len(result.invalid_events))import vayu "github.com/vayucode/vayu-sdks/go"
v := vayu.NewVayu(os.Getenv("VAYU_API_KEY"))
result, err := v.Events.SendEvents([]vayu.Event{
{
Name: "api_call",
Timestamp: time.Now().UTC(),
CustomerAlias: "customer-123",
Ref: "evt_abc123",
Data: map[string]interface{}{
"endpoint": "/users",
"method": "GET",
},
},
})
fmt.Println("Valid:", len(result.ValidEvents))
fmt.Println("Invalid:", len(result.InvalidEvents))curl -X PUT "https://connect.withvayu.com/events" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "x-api-key: $VAYU_CLIENT_ID" \
-d '{
"events": [
{
"name": "api_call",
"timestamp": "2026-04-14T12:00:00Z",
"customerAlias": "customer-123",
"ref": "evt_abc123",
"data": { "endpoint": "/users", "method": "GET" }
}
]
}'Response structure
The response includes two arrays:
validEvents— events that were successfully ingestedinvalidEvents— events that failed validation, each with an error message
{
"validEvents": [ { "name": "api_call", "ref": "evt_abc123", ... } ],
"invalidEvents": []
}Immediate availability
Events are available in the API and UI immediately after ingestion.
Invalid events do not cause the entire request to fail. They are returned in the invalidEvents array while valid events are still processed.