Push signed metric events from your own systems (Event API).
Send up to 100 events (500 metric points) to a push source you created in Settings → Grounding → Push sources. Authenticate with an API key holding write:events (when the source allows keys) or sign the request: Vouli-Source: <source id>, Vouli-Timestamp: <unix seconds>, Vouli-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>. The timestamp must be within ±5 minutes and each signature is accepted once. An event whose (external_id, type) the source sent before is counted as a duplicate and not written twice. Metric points become observations; a key with an approved metric definition that accepts the Event API is also stored in that governed series. Pushed values reach the signal bus near-real-time (seconds), and the AI only for sources an admin set to "use in AI". Requires an Idempotency-Key. org_id, source and any authorship field are refused by name at any depth.
- Authentication
Authorization: Bearer vk_…- Required scope
- write:events
- Rate limit
- Per key.
X-RateLimit-* on every response; a 429 carries Retry-After. - Idempotency
- Send an
Idempotency-Key; a retry with the same key replays the first response for 24h.
Request body (application/json, required)
Request body of POST /events| Field | Type | Description |
|---|
| events | array of object | 1–100 events, 500 metric points in total. Validated before anything is written. |
|---|
| strict? | boolean | true: a metric key with no approved definition refuses the whole batch (422 unmapped_metric). Default false: it is listed in unmapped_keys. |
|---|
{
"events": [
{
"entity": {
"attributes": {},
"external_id": "example_external_id",
"kind": "kpi"
},
"external_id": "example_external_id",
"metrics": [
{
"dimension": "example_dimension",
"key": "example_key",
"unit": "example_unit",
"value": 1
}
],
"occurred_at": "2026-01-01T00:00:00.000Z",
"type": "example_type"
}
],
"strict": true
}
Examples
curl
curl -X POST "https://www.vouliiq.com/api/v1/events" \
-H "Authorization: Bearer $VOULI_API_KEY" \
-H "Vouli-Version: 2026-09-12" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"events":[{"entity":{"attributes":{},"external_id":"example_external_id","kind":"kpi"},"external_id":"example_external_id","metrics":[{"dimension":"example_dimension","key":"example_key","unit":"example_unit","value":1}],"occurred_at":"2026-01-01T00:00:00.000Z","type":"example_type"}],"strict":true}'
TypeScript
// Not wrapped by the SDK: a plain HTTP call.
const res = await fetch('https://www.vouliiq.com/api/v1/events', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.VOULI_API_KEY}`,
'Vouli-Version': '2026-09-12',
'Idempotency-Key': crypto.randomUUID(),
'Content-Type': 'application/json',
},
body: JSON.stringify({
events: [
{
entity: {
attributes: {},
external_id: 'example_external_id',
kind: 'kpi',
},
external_id: 'example_external_id',
metrics: [
{
dimension: 'example_dimension',
key: 'example_key',
unit: 'example_unit',
value: 1,
},
],
occurred_at: '2026-01-01T00:00:00.000Z',
type: 'example_type',
},
],
strict: true,
}),
});
console.log(res.status, await res.json());
Python
# Not wrapped by the SDK: a plain HTTP call.
import json
import os
import urllib.request
import uuid
req = urllib.request.Request(
"https://www.vouliiq.com/api/v1/events",
method="POST",
headers={"Authorization": f"Bearer {os.environ['VOULI_API_KEY']}", "Vouli-Version": "2026-09-12", "Idempotency-Key": str(uuid.uuid4()), "Content-Type": "application/json"},
data=json.dumps({
"events": [
{
"entity": {
"attributes": {},
"external_id": "example_external_id",
"kind": "kpi",
},
"external_id": "example_external_id",
"metrics": [
{
"dimension": "example_dimension",
"key": "example_key",
"unit": "example_unit",
"value": 1,
},
],
"occurred_at": "2026-01-01T00:00:00.000Z",
"type": "example_type",
},
],
"strict": True,
}).encode(),
)
with urllib.request.urlopen(req) as res:
print(res.status, json.loads(res.read()))