ZeroDB · Event Streaming API
Publish events, trigger functions — react to data without polling
Publish named events with JSON payloads, subscribe via webhooks with topic and payload filters, batch-publish up to 100 events per call, and trigger ZeroDB Functions automatically. Same project, same API key.
Publish & subscribe
Publish events with any JSON payload. Subscribe via webhooks with per-field payload filters.
Batch publish (100/call)
Ship up to 100 events in a single request with partial_success support for high-throughput pipelines.
ZeroDB Functions
Register serverless hooks that fire automatically on matching topics — no polling, no infrastructure.
Quickstart
Base URL: https://api.ainative.studio Auth: X-API-Key: <your-project-api-key>
Publish a single event
POST /api/v1/public/zerodb/{project_id}/database/events
X-API-Key: <your-project-api-key>
{
"topic": "user.signup",
"event_payload": { "user_id": "u_1", "plan": "pro" }
}
# Returns:
# {
# "topic": "user.signup",
# "event_payload": { "user_id": "u_1", "plan": "pro" },
# "event_id": "...",
# "project_id": "...",
# "published_at": "2026-08-08T...Z"
# }Subscribe via webhook
POST /api/v1/public/zerodb/{project_id}/database/events/subscriptions
X-API-Key: <your-project-api-key>
{
"event_types": ["order.created", "user.signup"],
"webhook_url": "https://your-app.example.com/hooks/zerodb",
"filter": { "plan": "pro" } # only deliver events where payload.plan == "pro"
}
# Manage subscriptions:
GET /api/v1/public/zerodb/{project_id}/database/events/subscriptions
DELETE /api/v1/public/zerodb/{project_id}/database/events/subscriptions/{subscription_id}Batch publish (up to 100 events/call)
POST /api/v1/public/zerodb/{project_id}/database/events/batch
X-API-Key: <your-project-api-key>
{
"events": [
{ "topic": "user.login", "event_payload": { "user_id": "u_1" } },
{ "topic": "user.login", "event_payload": { "user_id": "u_2" } },
{ "topic": "order.placed", "event_payload": { "order_id": "o_99" } }
],
"partial_success": true # allow individual event failures without aborting the batch
}How events flow
Publish event
POST /database/events
Topic matching
subscription filter check
Webhook delivery
POST to webhook_url
ZeroDB Function
serverless trigger fires
Batch operation limits
Batch calls are 5–10x faster than sequential single-event calls.
| Endpoint | Max ops/call |
|---|---|
| /api/v1/public/zerodb/{project_id}/database/events/batch | 100 events |
| /api/v1/public/zerodb/{project_id}/database/batch/query (query/insert/update/delete) | 50 operations |
| /api/v1/public/zerodb/{project_id}/database/memory/batch/upsert · /update · /delete | 500 records |
Events per tier
| Tier | Events/month |
|---|---|
| Hobbyist (free) | 100K |
| Pro | 1M |
| Scale | 10M |
| Enterprise | Unlimited |
Patterns & anti-patterns
Patterns
- Use topics as contracts. Pick a stable naming convention (
noun.verb) early — topics are how subscriptions route. - Filter at subscription time. Use the payload filter on subscriptions to avoid fan-out to irrelevant webhooks.
- Batch the high-throughput paths. Collapse loops of single publishes into one /events/batch call.
- Set partial_success: true. Let a batch succeed even if a few events fail — catch failures in the response body.
Anti-patterns
- Wildcard subscriptions without filters. All events delivered to a slow webhook can back up and add latency.
- Polling instead of subscribing. The Events API is push — register a subscription instead of listing events on a loop.
- Very large event_payload. Keep payloads small (IDs and signals); store large objects in File Storage and reference them.
- No topic naming convention. Ad-hoc topic names make subscription management difficult as the event graph grows.
Get the Event Streaming Workbook — Publish, Subscribe & Trigger Functions
A free PDF guide: publish your first event, set up webhook subscriptions with filters, batch-publish for throughput, and wire ZeroDB Functions — step by step.
Frequently asked questions
What is the ZeroDB Event Streaming API?
The Events API lets you publish named events (topics) with arbitrary JSON payloads, subscribe to those events via webhooks with optional filters, and batch-publish up to 100 events per call. It is the backbone for event-driven workflows and for triggering ZeroDB Functions/hooks when data changes. All endpoints live under /api/v1/public/zerodb/{project_id}/database/events.
How do I publish an event?
POST to /api/v1/public/zerodb/{project_id}/database/events with a topic string (e.g. "user.signup") and an event_payload object. The API returns the event_id, project_id, and published_at timestamp.
How do I subscribe to events and receive webhooks?
POST to /api/v1/public/zerodb/{project_id}/database/events/subscriptions with event_types (array of topic strings), a webhook_url, and an optional filter object. The filter is matched against event_payload fields — only matching events are delivered to your webhook.
How does batch publishing work?
POST to /api/v1/public/zerodb/{project_id}/database/events/batch with an events array (up to 100 events per call) and optional partial_success: true to allow individual event failures without aborting the whole batch. Batch publishing is 5–10x faster than sequential single-event calls for high-throughput scenarios.
What are ZeroDB Functions / hooks?
ZeroDB Functions let you attach serverless logic to events — when a matching event is published, your function runs automatically. The Event Streaming API is the trigger layer: publish an event, and any registered function or webhook subscription with a matching topic fires. This enables data-reactive pipelines without polling.
Can I filter webhook deliveries?
Yes. When creating a subscription, pass a filter object with key-value pairs that are matched against the event_payload. For example, { "plan": "pro" } will only deliver events whose payload contains plan: "pro". Subscriptions without a filter receive all events matching their event_types.
