Skip to main content

HTTP API Reference

The DataBridge Gateway exposes a single endpoint for ingesting events from any platform or programming language.

Base URL​

https://cloud.databridge.tech/capture

Authentication​

All requests require the Api-Secret header containing the API secret generated when you create a Data Source in the dashboard:

Api-Secret: YOUR_SOURCE_API_SECRET

POST /capture​

Send one or more events in a single request.

Headers:

Content-Type: application/json
Api-Secret: YOUR_SOURCE_API_SECRET

Request Body:

{
  "header": {
    "client_timestamp_utc": 1705320600000,
    "client_tracker_name": "my-app",
    "client_tracker_version": "1.0.0"
  },
  "events": [
    {
      "$id": "https://registry.databridge.tech/acme/purchase_completed/1-0-0",
      "$eid": "550e8400-e29b-41d4-a716-446655440000",
      "order_id": "ORD-12345",
      "amount": 99.99,
      "currency": "USD"
    }
  ]
}

Fields​

header (required):

FieldTypeDescription
client_timestamp_utcintegerUnix timestamp in milliseconds
client_tracker_namestringName of the sending application
client_tracker_versionstringVersion of the sending application

events (required): Array of event objects. Each event contains:

FieldTypeRequiredDescription
$idstringYesSchema reference URL from the registry (namespace/name/version)
$eidstringYesUnique event ID (UUID) for deduplication
other fieldsanyNoEvent payload fields as defined in the schema

Event payload fields are placed directly at the top level of each event object - there is no properties wrapper.

Response​

200 OK - Events accepted for processing. The response body is empty.

info

Validation is asynchronous. A 200 response means the events were accepted into the processing queue. Schema validation results appear in the dashboard under the source's quality report.

401 Unauthorized - Invalid or missing api-secret header.

503 Service Unavailable - Internal queue is full. Retry with backoff.

Request Limits​

  • Maximum request body size: 1 MB
  • Events are always sent as an array, even for a single event

cURL Example​

curl -X POST https://cloud.databridge.tech/capture \
  -H "Content-Type: application/json" \
  -H "api-secret: YOUR_SOURCE_API_SECRET" \
  -d '{
    "header": {
      "client_timestamp_utc": 1705320600000,
      "client_tracker_name": "my-backend",
      "client_tracker_version": "1.0.0"
    },
    "events": [
      {
        "$id": "https://registry.databridge.tech/acme/purchase_completed/1-0-0",
        "$eid": "550e8400-e29b-41d4-a716-446655440000",
        "order_id": "ORD-12345",
        "amount": 99.99,
        "currency": "USD"
      }
    ]
  }'

Language Examples​

Python​

import requests
import uuid
import time

url = "https://cloud.databridge.tech/capture"
headers = {
    "Content-Type": "application/json",
    "api-secret": "YOUR_SOURCE_API_SECRET"
}

data = {
    "header": {
        "client_timestamp_utc": int(time.time() * 1000),
        "client_tracker_name": "my-python-app",
        "client_tracker_version": "1.0.0"
    },
    "events": [
        {
            "$id": "https://registry.databridge.tech/acme/purchase_completed/1-0-0",
            "$eid": str(uuid.uuid4()),
            "order_id": "ORD-12345",
            "amount": 99.99,
            "currency": "USD"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.status_code)  # 200 on success

Go​

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	"github.com/google/uuid"
)

func main() {
	data := map[string]interface{}{
		"header": map[string]interface{}{
			"client_timestamp_utc":  time.Now().UnixMilli(),
			"client_tracker_name":    "my-go-app",
			"client_tracker_version": "1.0.0",
		},
		"events": []map[string]interface{}{
			{
				"$id":      "https://registry.databridge.tech/acme/purchase_completed/1-0-0",
				"$eid":     uuid.New().String(),
				"order_id": "ORD-12345",
				"amount":   99.99,
				"currency": "USD",
			},
		},
	}

	jsonData, _ := json.Marshal(data)
	req, _ := http.NewRequest("POST", "https://cloud.databridge.tech/capture", bytes.NewBuffer(jsonData))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("api-secret", "YOUR_SOURCE_API_SECRET")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.StatusCode)
}

Best Practices​

  1. Always include $eid - Use UUIDs for event deduplication
  2. Batch events - Send multiple events in the events array to reduce HTTP overhead
  3. Implement retry logic - Retry on 503 responses with exponential backoff
  4. Register schemas first - Events are validated against schemas in the registry; unregistered events fall back to a generic payload column

Next Steps​