Events API

The Events API provides a unified interface for publishing events, querying the audit log, and subscribing to real-time event streams across all three platforms: MeshOS, Axis, and Smart Contracts.

Base URL

https://api.your-domain.com/v1

All endpoints require a valid API key. See the Authentication Guide for setup details.

Authentication

curl https://api.your-domain.com/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish Event

Publish an event to the unified event spine. Events can trigger workflows across MeshOS, Axis, and Smart Contracts depending on the event type.

Endpoint: POST /events

Request Body

{
type: string;          // required — dot-notation (e.g., "code.analysis.complete")
source: string;        // required — originating service or integration
data: object;          // required — event-specific payload
metadata?: {
  correlationId?: string;   // link related events across systems
  userId?: string;
  orgId?: string;
  tags?: string[];
}
}

Example: Publish a MeshOS Analysis Event

const response = await fetch('https://api.your-domain.com/v1/events', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json',
},
body: JSON.stringify({
  type: 'code.analysis.complete',
  source: 'github.action',
  data: {
    applicationId: 'app_abc123',
    repository: 'my-app',
    score: 72,
    issueCount: 14
  },
  metadata: {
    correlationId: 'run-gh-001',
    orgId: 'org_xyz'
  }
})
});

const result = await response.json();

Response

{
"eventId": "evt_abc123",
"type": "code.analysis.complete",
"timestamp": "2024-01-15T10:30:00Z",
"status": "published",
"workflowsTriggered": 1
}

Query Events

Retrieve events from the immutable audit log with filtering and pagination.

Endpoint: GET /events

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | type | string | Filter by event type (wildcards supported: code.*) | | source | string | Filter by originating source | | orgId | string | Filter to a specific organization | | from | ISO 8601 | Start of time range | | to | ISO 8601 | End of time range | | correlationId | string | Filter by correlation ID | | limit | integer | Results per page (max 100, default 20) | | offset | integer | Pagination offset |

Example

const params = new URLSearchParams({
type: 'code.*',
from: '2024-01-01T00:00:00Z',
limit: '50'
});

const response = await fetch(`https://api.your-domain.com/v1/events?${params}`, {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const { events, total } = await response.json();

Response

{
"events": [
  {
    "eventId": "evt_abc123",
    "type": "code.analysis.complete",
    "source": "meshos.analyzer",
    "orgId": "org_xyz",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": { ... },
    "metadata": { "correlationId": "run-gh-001" }
  }
],
"total": 312,
"offset": 0,
"limit": 50
}

Subscribe to Events (Webhook)

Register a webhook endpoint to receive events matching specific patterns in real time.

Endpoint: POST /events/subscriptions

Request Body

{
eventTypes: string[];      // patterns to match (wildcards supported)
webhookUrl: string;        // HTTPS endpoint to receive events
secret: string;            // used to compute HMAC-SHA256 signature
description?: string;
}

Example

const response = await fetch('https://api.your-domain.com/v1/events/subscriptions', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  eventTypes: ['code.*', 'lead.*', 'contract.*'],
  webhookUrl: 'https://your-app.com/webhooks/events',
  secret: 'whsec_xxxxxxxx',
  description: 'All platform events'
})
});

Webhook Payload

{
"subscriptionId": "sub_xyz789",
"deliveredAt": "2024-01-15T10:30:01Z",
"event": {
  "eventId": "evt_abc123",
  "type": "code.analysis.complete",
  "source": "meshos.analyzer",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": { ... }
}
}

The X-Signature header contains the HMAC-SHA256 of the raw request body. Verify it before processing:

import crypto from 'crypto';

function verifySignature(body: string, header: string, secret: string): boolean {
const expected = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('hex');
return crypto.timingSafeEqual(
  Buffer.from(`sha256=${expected}`),
  Buffer.from(header)
);
}

See the Webhooks API reference for delivery guarantees, retry behavior, and the full event catalog.

Manage Subscriptions

List Subscriptions

GET /events/subscriptions

Delete Subscription

DELETE /events/subscriptions/{subscriptionId}

Platform Event Types

Events follow resource.action[.status] naming. Common patterns by platform:

MeshOS

| Event Type | Trigger | |------------|---------| | code.upload.complete | ZIP file processed | | code.analysis.complete | Static analysis finished | | review.agent.complete | Individual AI agent finished | | review.multi-agent.complete | Full 20+ agent review done | | readiness.scored | Readiness assessment complete | | component.promoted | Component moved to registry | | application.approved | Application approved | | application.archived | Application archived |

Axis

| Event Type | Trigger | |------------|---------| | campaign.created | New campaign created | | campaign.launched | Campaign went live | | lead.enriched | Lead data enrichment complete | | lead.scored | ICP scoring complete | | outreach.sent | Message delivered | | outreach.replied | Reply received | | meeting.booked | Meeting scheduled | | compliance.blocked | Message blocked by compliance agent |

Smart Contracts

| Event Type | Trigger | |------------|---------| | contract.created | Contract record created | | contract.deployed | Contract deployed to chain | | contract.executed | Transaction executed | | contract.failed | Execution failed | | backup.completed | Backup finished | | scaling.node-added | Cluster scaled up | | alert.triggered | Monitoring alert fired |

Rate Limits

| Endpoint | Limit | |----------|-------| | POST /events | 1,000 req/min per org | | GET /events | 300 req/min per org | | POST /events/subscriptions | 10 active subscriptions per org |

Rate limit state is returned in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 742
X-RateLimit-Reset: 1705316400

Error Codes

| Code | HTTP | Description | |------|------|-------------| | invalid_event_type | 400 | Type must use dot notation | | missing_required_field | 400 | type, source, or data is missing | | payload_too_large | 413 | Event payload exceeds 1MB | | unauthorized | 401 | Missing or invalid API key | | forbidden | 403 | Insufficient scope for this operation | | rate_limit_exceeded | 429 | Too many requests |

{
"error": {
  "code": "invalid_event_type",
  "message": "Event type must follow dot notation (e.g., 'code.analysis.complete')",
  "field": "type"
}
}

Next Steps

• Webhooks Reference — delivery guarantees, retry schedule, HMAC verification
• Event Spine Concept — how events flow through the system
• Authentication — API keys, scopes, and rotation