Welcome back

API Key

Use this key to authenticate external app requests via HTTP.

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:

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);
  }
}