API Reference

API Reference

Complete reference for all DeltaBase APIs. These are the actual HTTP endpoints - most developers will use the SDK instead.

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer your-api-key

Management API

Administrative operations for event stores.

Create Event Store

POST /event-stores

Request Body:

{
  "name": "my-event-store",
  "description": "Event store for my application",
  "region": "us-west-1",
  "settings": {
    "retentionPeriodDays": 365,
    "maxStreamSizeBytes": 104857600
  }
}

Response:

{
  "id": "es_abc123",
  "name": "my-event-store",
  "description": "Event store for my application",
  "region": "us-west-1",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

List Event Stores

GET /event-stores?limit=50&offset=0&filter=my-app

Query Parameters:

• limit (number, optional): Maximum number of results (default: 50)
• offset (number, optional): Number of results to skip (default: 0)
• filter (string, optional): Filter by name

Get Event Store

GET /event-stores/{eventStoreId}

Response:

{
  "id": "es_abc123",
  "name": "my-event-store",
  "description": "Event store for my application",
  "region": "us-west-1",
  "status": "active",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "statistics": {
    "totalStreams": 1250,
    "totalEvents": 45000,
    "databaseSizeBytes": 2048576,
    "oldestEventTimestamp": "2024-01-01T00:00:00.000Z",
    "newestEventTimestamp": "2024-01-15T12:30:00.000Z"
  },
  "settings": {
    "retentionPeriodDays": 365,
    "maxStreamSizeBytes": 104857600
  }
}

Delete Event Store

DELETE /event-stores/{eventStoreId}

Response: 204 No Content

Event Store API

Core event streaming operations.

Append Events to Stream

POST /event-stores/{eventStoreId}/streams/{streamId}

Request Body:

{
  "events": [
    {
      "type": "user.created",
      "data": {
        "id": "user-123",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "metadata": {
        "userId": "admin-456",
        "ip": "192.168.1.1"
      }
    }
  ],
  "expectedStreamVersion": 5
}

Headers:

• Idempotency-Key (optional): Ensures request is processed only once

Response:

{
  "streamId": "user-123",
  "eventsAppended": 1,
  "currentStreamVersion": 6,
  "globalPosition": 12345
}

Status Codes:

• 200 - Success
• 409 - Version conflict (wrong expectedStreamVersion)

Read Stream Events

GET /event-stores/{eventStoreId}/streams/{streamId}?direction=forward&limit=100&fromStreamPosition=0

Query Parameters:

• direction (string): forward or backward (default: forward)
• limit (number): Maximum events to return (default: 100, max: 1000)
• fromStreamPosition (number): Start position in stream
• toStreamPosition (number): End position in stream

Response:

{
  "streamId": "user-123",
  "events": [
    {
      "streamId": "user-123",
      "streamPosition": 0,
      "globalPosition": 12345,
      "eventId": "evt_abc123",
      "type": "user.created",
      "data": {
        "id": "user-123",
        "email": "john@example.com",
        "name": "John Doe"
      },
      "metadata": {
        "userId": "admin-456",
        "ip": "192.168.1.1"
      },
      "schemaVersion": "1.0",
      "transactionId": "txn_def456",
      "createdAt": "2024-01-01T12:00:00.000Z"
    }
  ],
  "hasMore": false,
  "streamVersion": 5
}

Query Events

GET /event-stores/{eventStoreId}/events?types=user.created,user.updated&limit=50&after=2024-01-01T00:00:00Z

Query Parameters:

• types (string): Comma-separated event types
• streams (string): Comma-separated stream IDs
• limit (number): Maximum events (default: 100, max: 1000)
• offset (number): Skip events (default: 0)
• after (string): Events after timestamp (ISO 8601)
• before (string): Events before timestamp (ISO 8601)
• fromGlobalPosition (number): Start from global position
• direction (string): forward or backward

List Streams

GET /event-stores/{eventStoreId}/streams?limit=100&offset=0&streamType=user

Query Parameters:

• limit, offset: Pagination
• streamType (string): Filter by stream type (derived from stream ID prefix)
• hasEvents (boolean): Only streams with events

Event Bus API

Real-time event subscriptions.

Create Subscription

POST /event-stores/{eventStoreId}/subscribe

Request Body:

{
  "eventFilter": "user.*",
  "subscriberType": "webhook",
  "subscriberConfig": {
    "url": "https://myapp.com/webhooks/deltabase",
    "headers": {
      "Authorization": "Bearer webhook-secret"
    }
  },
  "retryPolicy": {
    "maxRetries": 3,
    "backoffMultiplier": 2,
    "initialBackoffMs": 1000
  },
  "position": "latest"
}

Subscription Types:

• webhook: HTTP POST to URL
• websocket: Real-time WebSocket delivery
• queue: Cloudflare Queue (coming soon)
• durable_object: Durable Object (coming soon)

Event Filter Patterns:

• *: All events
• user.*: All events starting with “user.”
• *.created: All events ending with “.created”
• user.created: Exact match

Response:

{
  "subscriptionId": "sub_abc123",
  "eventFilter": "user.*",
  "subscriberType": "webhook",
  "status": "active",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "lastDeliveryAttempt": null,
  "failedDeliveries": 0
}

List Subscriptions

GET /event-stores/{eventStoreId}/subscriptions

Get Subscription

GET /event-stores/{eventStoreId}/subscriptions/{subscriptionId}

Delete Subscription

DELETE /event-stores/{eventStoreId}/subscriptions/{subscriptionId}

WebSocket API

Real-time event streaming via WebSocket.

Connect

const ws = new WebSocket(
  'wss://api.delta-base.com/event-stores/{eventStoreId}/events/ws?apiKey=your-key'
);

Subscribe to Events

ws.send(JSON.stringify({
  action: 'subscribe',
  eventFilter: 'user.*',
  position: 'latest'
}));

Received Event Format

{
  "type": "event",
  "event": {
    "streamId": "user-123",
    "streamPosition": 0,
    "globalPosition": 12345,
    "eventId": "evt_abc123",
    "type": "user.created",
    "data": { "id": "user-123", "email": "john@example.com" },
    "createdAt": "2024-01-01T12:00:00.000Z"
  }
}

List WebSocket Connections

GET /event-stores/{eventStoreId}/websocket-connections

Close Connection

DELETE /event-stores/{eventStoreId}/websocket-connections/{clientId}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "STREAM_NOT_FOUND",
    "message": "Stream 'user-999' not found",
    "details": {
      "streamId": "user-999",
      "eventStoreId": "es_abc123"
    }
  }
}

Common Error Codes:

• UNAUTHORIZED (401): Invalid or missing API key
• FORBIDDEN (403): Insufficient permissions
• NOT_FOUND (404): Resource doesn’t exist
• VERSION_CONFLICT (409): Stream version mismatch
• RATE_LIMITED (429): Too many requests
• INTERNAL_ERROR (500): Server error

Rate Limits

• API requests: 1000 requests per minute per API key
• Event appends: 10,000 events per minute per event store
• WebSocket connections: 100 concurrent connections per API key

Headers included in responses:

• X-RateLimit-Limit: Requests allowed per window
• X-RateLimit-Remaining: Requests remaining in window
• X-RateLimit-Reset: When the window resets

When rate limited, retry with exponential backoff.