Air API

The Air service is the unified HTTP ingestion endpoint. It handles both real-time messaging (messages and events) and telemetry ingestion (logs, metrics, and traces).

Base URL: https://air.nextepoch.cloud

Ingest Data

POST /v1/ingest/{type}

Path Parameters:

Parameter	Type	Description
type	string	One of: messages, events, logs, metrics, traces

Headers:

Header	Required	Description
Authorization	Yes	Bearer <your-jwt-token>
Content-Type	Yes	application/json

Request Body:

{
  "entries": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      ...
    }
  ]
}

Maximum 1000 entries per request.

Response:

{
  "data": {
    "accepted": 5,
    "rejected": 0
  }
}

Entry Schemas

Message Entry

Used for agent-to-agent communication and commands. Delivered in real time to topic subscribers.

Field	Type	Required	Description
timestamp	string (ISO 8601)	Yes	When the message was sent
message	string	Yes	Message content
attributes	object	No	Arbitrary key-value pairs

Event Entry

Used for discrete occurrences like workflow triggers and state changes. Delivered in real time to topic subscribers.

Field	Type	Required	Description
timestamp	string (ISO 8601)	Yes	When the event occurred
name	string	Yes	Event name (e.g., workflow_started)
attributes	object	No	Arbitrary key-value pairs

Log Entry

Stored durably and queryable via the Insights API.

Field	Type	Required	Description
timestamp	string (ISO 8601)	Yes	When the log was created
level	string	No	debug, info, warn, error, fatal
message	string	Yes	Log message
attributes	object	No	Arbitrary key-value pairs

Metric Entry

Stored durably and queryable via the Insights API.

Field	Type	Required	Description
timestamp	string (ISO 8601)	Yes	When the metric was recorded
name	string	Yes	Metric name (e.g., http_request_duration_ms)
value	number	Yes	Metric value
tags	object	No	Key-value tags for grouping

Trace Entry

Stored durably and queryable via the Insights API.

Field	Type	Required	Description
timestamp	string (ISO 8601)	Yes	Span start time
trace_id	string	Yes	Trace identifier
span_id	string	Yes	Span identifier
parent_span_id	string	No	Parent span ID
name	string	Yes	Operation name
duration_ms	number	Yes	Span duration in milliseconds
status	string	No	ok, error
attributes	object	No	Arbitrary key-value pairs

Health Check

GET /health

Response:

{
  "status": "ok"
}