Overview
Axisforge Events is a real-time event streaming delivery service. The platform connects event producers with consumer applications over standard HTTPS connections:
- Publishers dispatch structured event batches to the gateway using standard HTTPS
POST requests.
- Subscribers consume real-time event feeds by maintaining an open HTTPS
GET connection that delivers events via chunked streaming.
Both publishing and subscription share the canonical path /api/v1/sync/events and use the same project authentication token.
Regional Base URLs
Axisforge Events provides two regional access points. Both endpoints expose identical API methods, path structures, and authorization keys:
| Region |
Base URL |
Routing Details |
| Europe (Default) |
https://api.axisforge.tech |
Direct connection to Frankfurt origin clusters. |
| CIS |
https://cis.axisforge.tech |
Delivered through a regional edge partner to improve reachability and stabilize routing. |
All event processing, deduplication, and persistent data storage occur within our Frankfurt facility. For clients located in CIS territories (including Kazakhstan, Armenia, Georgia, and Uzbekistan), the regional edge partner relays HTTPS traffic to the Frankfurt origin, avoiding volatile transit paths.
Authentication
Authentication is supplied through the t URL query parameter:
https://api.axisforge.tech/api/v1/sync/events?t=YOUR_API_KEY
The API key identifies your workspace and authorizes both publish (POST) and stream subscription (GET) requests. If the t query parameter is omitted from a request, the gateway returns an HTTP 401 Unauthorized response.
Publishing Events (POST)
POST
/api/v1/sync/events?t=YOUR_API_KEY
Publishes a batch of event records into the delivery pipeline. Upon validation, the server confirms receipt with an empty 200 OK response, and distributes events to active subscribers immediately.
Request Headers
Content-Type: application/json
Subscribing to a Stream (GET)
GET
/api/v1/sync/events?t=YOUR_API_KEY
Subscribes to live event delivery over a persistent HTTPS connection using chunked transfer streaming. The server streams newly published events for your workspace as they arrive; each received chunk contains one or more event records.
Subscriber applications process incoming chunks as they are delivered and select events by their channel attribute. If network transit interrupts the connection, consumer clients should reconnect with an exponential backoff strategy.
JSON Batch Schema
The publish request body must be a valid JSON object specifying a channel, a producer source, and an array of event objects:
{
"channel": "telemetry-prod",
"source": "billing-service",
"events": [
{
"timestamp": "2026-10-04T12:00:00Z",
"level": "INFO",
"event_type": "invoice.generated",
"payload": {
"invoice_id": "inv_9042",
"customer_id": "cust_881",
"amount_eur": 420.00
}
},
{
"timestamp": "2026-10-04T12:00:01Z",
"level": "WARN",
"event_type": "gateway.latency_elevated",
"payload": {
"provider": "sepa_batch",
"duration_ms": 340
}
}
]
}
Limits & Recommendations
- Maximum Request Payload Size: Up to 512 KiB per POST request (up to 256 KiB under the Developer tier). Batches exceeding this size are rejected at the ingress edge.
- Recommended Batch Sizing: We recommend batching 50 to 500 records (approx. 50–250 KiB) per dispatch for balanced network efficiency and timely propagation.
- Monthly Stream Volume: Defined as the total sum of events ingested from publishers plus events delivered to active subscribers within a calendar month.
- Concurrent Streams: 1 active subscriber connection on Developer, 5 on Growth, and unlimited dedicated connections on Enterprise.
Response Status Codes
The gateway returns standard HTTP status codes:
200 OK — Success
For POST requests: Event batch accepted and distributed to delivery channels. Returns an empty response body.
For GET requests: Connection established. The server streams real-time events as chunked response data.
401 Unauthorized — Missing Token Parameter
The request omitted the required t query parameter:
{"error":"unauthorized","code":401,"message":"Authentication token required for event streaming"}
429 Too Many Requests — Stream Volume Quota Exceeded
The workspace has consumed its monthly allocated event volume. Responses include a Retry-After: 86400 header indicating the window until automatic recovery:
{"error":"quota_exceeded","code":429,"message":"Monthly event synchronization quota exceeded. Bandwidth suspended."}
Retry Policy
In the event of transient network drops or HTTP 429 quota notices, clients should execute an exponential backoff with full jitter before reconnecting or republishing:
Wait_Time = Min(Max_Backoff, Initial_Backoff * 2^attempt) + Uniform_Random(0, Jitter_Span)
Code Examples
Below are production examples for event publishers (POST) and stream subscribers (GET).
1. Publishing via cURL
curl -X POST "https://api.axisforge.tech/api/v1/sync/events?t=YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"channel": "telemetry-prod",
"source": "cli-publisher",
"events": [
{
"timestamp": "2026-10-04T12:00:00Z",
"level": "INFO",
"event_type": "deploy.completed",
"payload": {"version": "v2.14.0", "duration_sec": 42}
}
]
}'
2. Python (Publish & Subscribe)
import requests
API_URL = "https://api.axisforge.tech/api/v1/sync/events"
API_KEY = "YOUR_API_KEY"
# Publisher Example (POST)
def publish_batch(channel, events):
payload = {
"channel": channel,
"source": "order-processor",
"events": events
}
response = requests.post(
API_URL,
params={"t": API_KEY},
json=payload,
timeout=10
)
if response.status_code == 200:
print("Events published successfully.")
elif response.status_code == 429:
retry_after = int(response.headers.get("Retry-After", 86400))
print(f"Monthly quota reached. Retry after {retry_after}s.")
else:
response.raise_for_status()
# Subscriber Example (GET Streaming)
def subscribe_stream(target_channel):
response = requests.get(
API_URL,
params={"t": API_KEY},
stream=True,
timeout=60
)
response.raise_for_status()
for chunk in response.iter_content(chunk_size=None):
if chunk:
# Each chunk contains one or more event records for your channels
handle_chunk(chunk, target_channel)
3. Node.js (Publish & Subscribe)
const API_URL = "https://api.axisforge.tech/api/v1/sync/events";
const API_KEY = "YOUR_API_KEY";
// Publisher Example (POST)
async function publishEvents(channel, events) {
const payload = {
channel: channel,
source: "node-service",
events: events
};
const res = await fetch(`${API_URL}?t=${API_KEY}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload)
});
if (res.status === 200) {
console.log("Batch published successfully.");
} else if (res.status === 429) {
const retrySec = res.headers.get("Retry-After") || 86400;
console.warn(`Monthly quota reached. Retry after ${retrySec}s.`);
} else {
throw new Error(`Publish failed with HTTP ${res.status}`);
}
}
// Subscriber Example (GET Streaming)
async function subscribeStream(target_channel) {
const res = await fetch(`${API_URL}?t=${API_KEY}`, { method: "GET" });
if (!res.ok) {
throw new Error(`Subscription failed with HTTP ${res.status}`);
}
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { value, done } = await reader.read();
if (done) break;
// Each chunk contains one or more event records for your channels
handleChunk(decoder.decode(value, { stream: true }), target_channel);
}
}
Regional Endpoint Note: Customers in CIS use https://cis.axisforge.tech with the same path and API key.
Notice: This documentation outlines the HTTPS API specification for Axisforge Events. In compliance with security standards, the public marketing pages of this website do not invoke or record data to this endpoint.