Skip to content

API Reference

Complete reference for all Aegis REST API endpoints.

Base URLs

  • Production: https://aegisagent.ai
  • Intel Dashboard: https://intel.aegisagent.ai
  • Internal: http://localhost:8080 (within LXC)

Authentication

Most endpoints are public or use simple API key authentication.

API Key Authentication

Pass API key via header: 

curl -H "x-api-key: YOUR_KEY" https://aegisagent.ai/api/endpoint

Tiers: - Anonymous: 100 requests/hour - Authenticated: 1000 requests/hour

System Endpoints

GET /health

Health check endpoint for monitoring.

Response: 

{
  "status": "healthy",
  "database": "connected"
}

Example: 

curl https://aegisagent.ai/health

GET /api/status

Get system operational status.

Response: 

{
  "status": "operational",
  "phase": 3,
  "version": "4.15",
  "timestamp": "2026-01-25T10:00:00Z"
}

Example: 

curl https://aegisagent.ai/api/status

GET /api/rate-limit

Check your current rate limit status.

Response: 

{
  "tier": "anonymous",
  "limit_per_hour": 100,
  "remaining": 87,
  "reset_seconds": 1234,
  "authenticated": false
}

Example: 

curl -H "x-api-key: YOUR_KEY" https://aegisagent.ai/api/rate-limit

GET /api/tasks

Get task queue statistics.

Response: 

{
  "pending": 5,
  "in_progress": 2,
  "completed": 143,
  "failed": 3
}

GET /api/ooda

Get recent OODA cycle statistics.

Response: 

{
  "success_rate": 0.92,
  "recent_cycles": 10
}

GET /api/memory/recent

Get recent episodic memories.

Response: 

{
  "memories": [
    {
      "id": 123,
      "event_type": "decision",
      "summary": "Deployed nginx service",
      "importance": 8,
      "timestamp": "2026-01-25T09:30:00Z"
    }
  ]
}

Research Endpoints

GET /api/research

List recent research results.

Parameters: - limit (int, optional): Maximum results (default: 10)

Response: 

{
  "results": [
    {
      "id": 1,
      "topic": "AI agent memory systems",
      "status": "completed",
      "sources": 7,
      "created_at": "2026-01-25T08:00:00Z"
    }
  ],
  "count": 1
}

Example: 

curl https://aegisagent.ai/api/research?limit=5

GET /api/research/search

Search past research by keyword.

Parameters: - q (string, required): Search query - limit (int, optional): Maximum results (default: 10)

Response: 

{
  "query": "knowledge graphs",
  "results": [...],
  "count": 3
}

Example: 

curl "https://aegisagent.ai/api/research/search?q=knowledge%20graphs"

GET /api/research/{research_id}

Get specific research result by ID.

Response: 

{
  "id": 1,
  "topic": "AI agent memory systems",
  "content": "# Research Summary\n\n...",
  "sources": ["url1", "url2"],
  "status": "completed",
  "created_at": "2026-01-25T08:00:00Z"
}

Example: 

curl https://aegisagent.ai/api/research/123

POST /api/research

Create a new research request (requires API key).

Request Body: 

{
  "topic": "Agent orchestration patterns",
  "urls": ["https://example.com"],
  "search_query": "AI agent orchestration 2026",
  "max_sources": 5
}

Response: 

{
  "status": "queued",
  "topic": "Agent orchestration patterns",
  "message": "Research request queued. Use /api/research to check results.",
  "request": {...}
}

Example: 

curl -X POST https://aegisagent.ai/api/research \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Agent orchestration patterns", "max_sources": 5}'

Intel Dashboard Endpoints

GET /intel

Intel dashboard web interface (HTML).

Access at: https://intel.aegisagent.ai

GET /api/intel/briefings

List all intelligence briefings.

Parameters: - limit (int, optional): Maximum results (default: 20)

Response: 

{
  "briefings": [
    {
      "filename": "2026-01-25-middle-east-crisis.md",
      "title": "Middle East Crisis Assessment",
      "date": "2026-01-25",
      "region": "Middle East",
      "depth": "Standard",
      "confidence": "High",
      "summary": "Analysis of recent developments..."
    }
  ],
  "total": 15
}

Example: 

curl https://intel.aegisagent.ai/api/intel/briefings?limit=10

GET /api/intel/briefing/{filename}

Get specific briefing content.

Parameters: - email (string, optional): For tier verification

Response: 

{
  "title": "Middle East Crisis Assessment",
  "content": "# Middle East Crisis Assessment\n\n..."
}

Access Denied Response: 

{
  "title": "Middle East Crisis Assessment",
  "preview": "First 500 characters...",
  "access_denied": true,
  "reason": "Regional tier required",
  "upgrade_url": "https://buy.stripe.com/...",
  "upgrade_tier": "Regional ($79/mo)",
  "message": "This Standard depth briefing requires a Regional ($79/mo) subscription."
}

Example: 

curl "https://intel.aegisagent.ai/api/intel/briefing/2026-01-25-middle-east.md?email=user@example.com"

POST /api/intel/generate

Request briefing generation (placeholder).

Request Body: 

{
  "event": "US-China trade negotiations",
  "depth": "standard"
}

Depths: quick, standard, deep

Response: 

{
  "status": "queued",
  "message": "Briefing generation requested for: US-China trade negotiations",
  "depth": "standard",
  "note": "Use /geoint skill for immediate generation"
}

Example: 

curl -X POST https://intel.aegisagent.ai/api/intel/generate \
  -H "Content-Type: application/json" \
  -d '{"event": "US-China trade negotiations", "depth": "standard"}'

GET /api/intel/notebooks

List available regional notebooks.

Response: 

{
  "notebooks": [
    {
      "name": "Latin America",
      "sources": 47,
      "id": "nb_latam_001"
    }
  ]
}

POST /api/intel/subscribe

Subscribe email to intel mailing list.

Request Body: 

{
  "email": "user@example.com"
}

Response: 

{
  "status": "success",
  "message": "Successfully subscribed to Aegis Intel"
}

Example: 

curl -X POST https://intel.aegisagent.ai/api/intel/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

GET /api/intel/sample-pdf

Download sample intelligence report PDF.

Response: PDF file download

Example: 

curl -O https://intel.aegisagent.ai/api/intel/sample-pdf

POST /api/intel/deep-briefing

Generate a comprehensive deep intelligence briefing.

Request Body: 

{
  "topic": "Economic sanctions impact",
  "location": "Russia",
  "date": "January 2026",
  "method": "perplexity",
  "email": "user@example.com"
}

Methods: perplexity (~$1-2), gemini (~$3-5)

Response: 

{
  "job_id": "uuid-here",
  "status": "pending",
  "topic": "Economic sanctions impact",
  "location": "Russia",
  "method": "perplexity",
  "message": "Deep briefing generation queued. Estimated time: 2-5 minutes. Cost: ~$2."
}

Tier Enforcement: - Explorer (free): Not available - Regional: 1 deep briefing/month - Global/Enterprise: Unlimited

Example: 

curl -X POST https://intel.aegisagent.ai/api/intel/deep-briefing \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Economic sanctions impact",
    "location": "Russia",
    "method": "perplexity",
    "email": "user@example.com"
  }'

GET /api/intel/deep-briefing/{job_id}

Get deep briefing job status and content.

Response (pending): 

{
  "job_id": "uuid-here",
  "topic": "Economic sanctions impact",
  "location": "Russia",
  "status": "processing",
  "created_at": "2026-01-25T10:00:00Z"
}

Response (completed): 

{
  "job_id": "uuid-here",
  "topic": "Economic sanctions impact",
  "location": "Russia",
  "status": "completed",
  "content": "# Deep Intelligence Briefing\n\n...",
  "metadata": {
    "total_tokens": 15000,
    "total_sources": 12,
    "generation_time_seconds": 180,
    "estimated_cost": 2.45,
    "filepath": "/home/agent/memory/intel/..."
  },
  "created_at": "2026-01-25T10:00:00Z",
  "completed_at": "2026-01-25T10:03:00Z"
}

GET /api/intel/deep-briefings

List recent deep briefing jobs.

Parameters: - limit (int, optional): Maximum results (default: 20)

Response: 

{
  "jobs": [
    {
      "job_id": "uuid-here",
      "topic": "Economic sanctions impact",
      "location": "Russia",
      "status": "completed",
      "method": "perplexity",
      "metadata": {...},
      "created_at": "2026-01-25T10:00:00Z",
      "completed_at": "2026-01-25T10:03:00Z"
    }
  ],
  "total": 5
}

POST /api/intel/region

Set region preference for Regional tier subscribers.

Request Body: 

{
  "email": "user@example.com",
  "region": "latin-america"
}

Available Regions: - latin-america - africa - asia-pacific - eastern-europe - middle-east

Response: 

{
  "status": "success",
  "message": "Region preference set to latin-america",
  "region": "latin-america"
}

GET /api/intel/subscribers

Get list of all active subscribers (admin).

Response: 

{
  "total": 42,
  "subscribers": [
    {
      "email": "user@example.com",
      "tier": "regional",
      "subscribed_at": "2026-01-20T12:00:00Z"
    }
  ]
}

POST /api/intel/digest/send

Send digest emails to subscribers (admin, requires key).

Request Body: 

{
  "frequency": "weekly",
  "admin_key": "YOUR_ADMIN_KEY"
}

Frequencies: weekly, daily

Response: 

{
  "status": "queued",
  "message": "Weekly digest sending in background",
  "frequency": "weekly"
}

GET /api/intel/digest/preview

Preview digest content without sending.

Parameters: - frequency (string, optional): weekly or daily (default: weekly) - region (string, optional): Filter by region

Response: 

{
  "content": "# Weekly Intelligence Digest\n\n...",
  "frequency": "weekly",
  "region": "latin-america",
  "days": 7
}

Example: 

curl "https://intel.aegisagent.ai/api/intel/digest/preview?frequency=weekly&region=latin-america"

WhatsApp/Vonage Endpoints

POST /api/vonage/whatsapp/inbound

Webhook for inbound WhatsApp messages (called by Vonage).

Request Body (from Vonage): 

{
  "message_uuid": "abc-123",
  "from": "447490195079",
  "to": "447441443388",
  "timestamp": "2026-01-25T10:00:00Z",
  "message_type": "text",
  "text": "status",
  "channel": "whatsapp"
}

Response: 

{
  "status": "accepted"
}

POST /api/vonage/whatsapp/status

Webhook for WhatsApp delivery status (called by Vonage).

Request Body (from Vonage): 

{
  "message_uuid": "abc-123",
  "to": "447490195079",
  "from": "447441443388",
  "status": "delivered",
  "channel": "whatsapp"
}

Response: 

{
  "status": "accepted"
}

GET /api/vonage/whatsapp/status

Get WhatsApp integration status and configuration.

Response: 

{
  "configured": true,
  "vonage_app_id": "3b60dc5c-...",
  "whatsapp_number": "447441443388",
  "authorized_numbers": ["447490195079", "447816246275"],
  "registered_intents": ["status", "tasks", "deploy", ...],
  "handlers_registered": 12,
  "webhook_urls": {
    "inbound": "https://aegisagent.ai/api/vonage/whatsapp/inbound",
    "status": "https://aegisagent.ai/api/vonage/whatsapp/status"
  }
}

POST /api/vonage/whatsapp/send

Send a WhatsApp message (admin).

Request Body: 

{
  "to": "447490195079",
  "text": "Hello from Aegis!"
}

Response: 

{
  "ok": true,
  "message_uuid": "abc-123"
}

GET /api/vonage/whatsapp/sessions

List active WhatsApp sessions.

Response: 

{
  "sessions": [
    {
      "phone_number": "447490195079",
      "last_intent": "status",
      "updated_at": "2026-01-25T10:00:00Z",
      "notifications": "enabled"
    }
  ],
  "count": 1
}

GET /api/vonage/whatsapp/messages

List recent WhatsApp messages.

Parameters: - phone_number (string, optional): Filter by phone - limit (int, optional): Maximum results (default: 50)

Response: 

{
  "messages": [
    {
      "phone_number": "447490195079",
      "direction": "inbound",
      "content": "status",
      "intent": "status",
      "created_at": "2026-01-25T10:00:00Z"
    }
  ],
  "count": 23
}

POST /api/vonage/whatsapp/test

Send test WhatsApp message.

Response: 

{
  "test_sent_to": "447490195079",
  "success": true,
  "message_uuid": "abc-123"
}

POST /api/vonage/sms/inbound

Webhook for inbound SMS messages (called by Vonage).

Accepts both GET and POST requests with form-encoded or JSON data.

File Sharing Endpoints

POST /api/files/share

Create a shareable link for a file.

Request Body: 

{
  "file_path": "/home/agent/memory/semantic/document.md",
  "expires_hours": 24
}

Expires: 1-168 hours (default: 24)

Allowed Paths: - /home/agent/memory/ - /home/agent/projects/aegis-core/data/

Response: 

{
  "url": "https://aegisagent.ai/share/abc123def456",
  "expires_at": "2026-01-26T10:00:00Z",
  "file_path": "/home/agent/memory/semantic/document.md",
  "created_at": "2026-01-25T10:00:00Z"
}

Example: 

curl -X POST https://aegisagent.ai/api/files/share \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/home/agent/memory/semantic/document.md",
    "expires_hours": 48
  }'

GET /share/{token}

Access a shared file (Markdown viewer).

Query Parameters: - download=true: Download file instead of viewing - raw=true: Return raw content

Example: 

# View in browser
https://aegisagent.ai/share/abc123def456

# Download
https://aegisagent.ai/share/abc123def456?download=true

# Raw content
https://aegisagent.ai/share/abc123def456?raw=true

Stripe Webhook

POST /api/stripe/webhook

Handle Stripe payment events for Intel subscriptions.

Events Handled: - checkout.session.completed: New subscription - customer.subscription.updated: Subscription modified - customer.subscription.deleted: Subscription cancelled - invoice.payment_failed: Payment failed

Response: 

{
  "status": "ok"
}

Note: Requires valid Stripe signature in stripe-signature header.

Error Responses

All endpoints return standard error formats:

400 Bad Request: 

{
  "detail": "Missing required parameter: topic"
}

401 Unauthorized: 

{
  "detail": "Invalid API key"
}

403 Forbidden: 

{
  "detail": "Number not in authorized list"
}

404 Not Found: 

{
  "detail": "Briefing not found"
}

429 Too Many Requests: 

{
  "detail": "Rate limit exceeded. Try again in 1234 seconds."
}

500 Internal Server Error: 

{
  "detail": "Internal server error"
}

Rate Limits

Tier Limit Reset
Anonymous 100/hour Hourly
Authenticated 1000/hour Hourly

Check your limit: GET /api/rate-limit

CORS

All endpoints support CORS for browser requests.

SDK Usage

For Python applications, use the MCP tools or direct HTTP:

import httpx

# Research API
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://aegisagent.ai/api/research",
        headers={"x-api-key": "YOUR_KEY"},
        json={"topic": "AI agents", "max_sources": 5}
    )
    result = response.json()

See Also