Welcome back

Integrating an app? Start here

This page is a complete, self-contained spec for connecting one of your apps to the cortex brains. To integrate a new app, hand the full spec below to an AI session that has context of that app and ask it to propose a plan, then build the integration.

The copied spec includes the event envelope, both ingress methods, routing rules, and the live capability catalog (every domain.action each brain accepts) — everything an agent needs to plan and implement.

External Integration

Connect external apps to the cortex using bidirectional events. External apps can push events into the cortex (triggering brain actions), and brains can publish events out to external apps.

External App                         Cortex
────────────                         ──────
               ── publish event ──→  EventBridge  ──→  ALICE classifies
               ←── brain event  ──   EventBridge  ←──  Brain takes action

Two ingress methods:
  1. HTTP: POST /api/core/external/events (X-API-Key auth)
  2. AWS EventBridge: PutEvents to "cortex-events" bus

Event Envelope

All events use this standard envelope format:

{
  "source": "external.your-app-name",
  "type": "domain.action",
  "brain": "auto",
  "priority": "normal",
  "payload": { ... },
  "correlationId": "optional-uuid",
  "timestamp": "optional-iso8601"
}

Publishing Events via HTTP

The simplest way to send events. Authenticate with your API key.

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "external.email-app",
    "type": "email.received",
    "brain": "auto",
    "priority": "high",
    "payload": {
      "from": "lawyer@firm.com",
      "subject": "Contract Review Required",
      "body": "Please review the attached NDA..."
    }
  }' \
  https://alice.ensomniamedia.com/api/core/external/events

{
  "accepted": true,
  "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Publishing Events via EventBridge

For apps running in AWS, publish directly to the cortex-events EventBridge bus.

// Node.js / AWS SDK v3
import { EventBridgeClient, PutEventsCommand } from '@aws-sdk/client-eventbridge';

const client = new EventBridgeClient({});
await client.send(new PutEventsCommand({
  Entries: [{
    EventBusName: 'cortex-events',
    Source: 'external.my-app',
    DetailType: 'payment.received',
    Detail: JSON.stringify({
      source: 'external.my-app',
      type: 'payment.received',
      brain: 'finance',
      priority: 'normal',
      payload: { amount: 150.00, vendor: 'AWS', category: 'infrastructure' }
    })
  }]
}));

AWS CLI equivalent:

aws events put-events --entries '[{
  "EventBusName": "cortex-events",
  "Source": "external.my-app",
  "DetailType": "payment.received",
  "Detail": "{\"source\":\"external.my-app\",\"type\":\"payment.received\",\"brain\":\"finance\",\"payload\":{\"amount\":150}}"
}]'

Receiving Events from Brains

Brains publish events to the cortex-events bus with source cortex.{brainId}. Create an EventBridge rule to subscribe.

// CDK example: subscribe to all cortex brain events
const rule = new events.Rule(this, 'CortexListener', {
  eventBus: events.EventBus.fromEventBusName(this, 'CortexBus', 'cortex-events'),
  eventPattern: {
    source: [{ prefix: 'cortex.' }]
  },
});
rule.addTarget(new eventsTargets.LambdaFunction(myHandler));

You can filter by specific brain or event type:

// Only listen to finance brain events
eventPattern: { source: ['cortex.finance'] }

// Only listen to task completion events
eventPattern: { source: [{ prefix: 'cortex.' }], detailType: ['tasks.completed'] }

Routing

Events are routed based on the brain field in the envelope:

Brain Reference

Available brains and what they handle (loaded live from the registry):

Capability Catalog

Every domain.action you can target. For direct routing, set "brain" to the brain id and "type" to "domain.action" (e.g. finance + transactions.create). Loaded live from the registry.

Integration Examples

Email App

Forward emails to ALICE for classification. She'll route to the right brain automatically.

// Your email sync app detects a new email
await fetch('https://alice.ensomniamedia.com/api/core/external/events', {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    source: 'external.gmail-sync',
    type: 'email.received',
    brain: 'auto',  // ALICE decides: legal? finance? core?
    priority: 'normal',
    payload: {
      from: 'accountant@firm.com',
      subject: 'Q1 Tax Documents Ready',
      body: 'Your quarterly tax prep documents are ready for review...',
      receivedAt: '2026-03-23T10:30:00Z'
    }
  })
});

Banking App (Direct Routing)

When you know the target brain, skip ALICE and route directly.

// Banking app detects a new transaction
{
  "source": "external.bank-sync",
  "type": "transactions.create",
  "brain": "finance",  // Direct to finance brain
  "payload": {
    "amount": -89.99,
    "description": "AWS Monthly Bill",
    "category": "infrastructure",
    "date": "2026-03-23"
  }
}

Listening for Brain Events

Your apps can react when brains take action.

// Your notification app listens for cortex events
// EventBridge rule: source = cortex.*, target = your Lambda

export async function handler(event) {
  const detail = event.detail;

  if (detail.source === 'cortex.finance' && detail.type === 'bills.overdue') {
    await sendPushNotification('Overdue bill!', detail.payload);
  }

  if (detail.source === 'cortex.devops' && detail.type === 'alerts.critical') {
    await pageOncall(detail.payload);
  }
}