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

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

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

Authentication

1curl https://api.your-domain.com/v1/events \
2  -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

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

Example: Publish a MeshOS Analysis Event

1const response = await fetch('https://api.your-domain.com/v1/events', {
2method: 'POST',
3headers: {
4  'Authorization': 'Bearer YOUR_API_KEY',
5  'Content-Type': 'application/json',
6},
7body: JSON.stringify({
8  type: 'code.analysis.complete',
9  source: 'github.action',
10  data: {
11    applicationId: 'app_abc123',
12    repository: 'my-app',
13    score: 72,
14    issueCount: 14
15  },
16  metadata: {
17    correlationId: 'run-gh-001',
18    orgId: 'org_xyz'
19  }
20})
21});
22
23const result = await response.json();

Response

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

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

1const params = new URLSearchParams({
2type: 'code.*',
3from: '2024-01-01T00:00:00Z',
4limit: '50'
5});
6
7const response = await fetch(`https://api.your-domain.com/v1/events?${params}`, {
8headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
9});
10
11const { events, total } = await response.json();

Response

1{
2"events": [
3  {
4    "eventId": "evt_abc123",
5    "type": "code.analysis.complete",
6    "source": "meshos.analyzer",
7    "orgId": "org_xyz",
8    "timestamp": "2024-01-15T10:30:00Z",
9    "data": { ... },
10    "metadata": { "correlationId": "run-gh-001" }
11  }
12],
13"total": 312,
14"offset": 0,
15"limit": 50
16}

Subscribe to Events (Webhook)

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

Endpoint: POST /events/subscriptions

Request Body

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

Example

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

Webhook Payload

1{
2"subscriptionId": "sub_xyz789",
3"deliveredAt": "2024-01-15T10:30:01Z",
4"event": {
5  "eventId": "evt_abc123",
6  "type": "code.analysis.complete",
7  "source": "meshos.analyzer",
8  "timestamp": "2024-01-15T10:30:00Z",
9  "data": { ... }
10}
11}

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

1import crypto from 'crypto';
2
3function verifySignature(body: string, header: string, secret: string): boolean {
4const expected = crypto
5  .createHmac('sha256', secret)
6  .update(body)
7  .digest('hex');
8return crypto.timingSafeEqual(
9  Buffer.from(`sha256=${expected}`),
10  Buffer.from(header)
11);
12}

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

Manage Subscriptions

List Subscriptions

1GET /events/subscriptions

Delete Subscription

1DELETE /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:

1X-RateLimit-Limit: 1000
2X-RateLimit-Remaining: 742
3X-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 |

1{
2"error": {
3  "code": "invalid_event_type",
4  "message": "Event type must follow dot notation (e.g., 'code.analysis.complete')",
5  "field": "type"
6}
7}

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