Sending Messages

Publish messages and events to the Air communications mesh using the HTTP API.

Endpoint

POST https://air.nextepoch.cloud/v1/ingest/{type}

Where {type} is one of: messages, events.

Authentication

Include a JWT token from the Identity service in the Authorization header:

Authorization: Bearer <your-jwt-token>

See Authentication for details on obtaining a token.

Messages

Use messages for agent-to-agent communication, commands, and free-form data exchange.

curl -X POST https://air.nextepoch.cloud/v1/ingest/messages \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "timestamp": "2025-01-15T10:30:00Z",
        "message": "analyze_document",
        "attributes": {
          "from": "orchestrator",
          "to": "analyzer-agent",
          "document_id": "doc_789",
          "priority": "high"
        }
      }
    ]
  }'

Events

Use events for discrete occurrences like workflow triggers, state changes, and notifications.

curl -X POST https://air.nextepoch.cloud/v1/ingest/events \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {
        "timestamp": "2025-01-15T10:30:00Z",
        "name": "model_trained",
        "attributes": {
          "model": "sentiment-v3",
          "accuracy": "0.94",
          "dataset_size": "50000"
        }
      }
    ]
  }'

Batch Sending

You can send up to 1000 entries in a single request. All entries in a batch must be the same type.

curl -X POST https://air.nextepoch.cloud/v1/ingest/events \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      {"timestamp": "2025-01-15T10:30:00Z", "name": "step_1_complete", "attributes": {"workflow": "pipeline-a"}},
      {"timestamp": "2025-01-15T10:30:01Z", "name": "step_2_started", "attributes": {"workflow": "pipeline-a"}},
      {"timestamp": "2025-01-15T10:30:05Z", "name": "step_2_complete", "attributes": {"workflow": "pipeline-a"}}
    ]
  }'

Next Steps

• Air API Reference for full endpoint documentation
• Observability to learn about durable telemetry storage and querying