Skip to content

Message + Edge Ingest Endpoints

Last Updated: 2026-02-16

This document describes the current HTTP ingest endpoints used by: - the Mac mini edge relay (../archety-edge) - legacy relays that still call the original orchestrator endpoint

Endpoint Summary

Endpoint Purpose Schema Auth
POST /edge/message Primary edge ingest FilteredMessage Authorization: Bearer <edge_token>
POST /orchestrator/message Legacy ingest OrchestratorRequest Authorization: Bearer <relay_secret> (if configured)

Related real-time transport: - WS /edge/ws?edge_agent_id=... (edge command delivery) - POST /edge/sync (edge polling fallback)

1) POST /edge/message (Primary)

Backend route: app/api/edge_routes.py
Schema: app/edge/schemas.py::FilteredMessage

Authentication

Authorization: Bearer <edge_token>

<edge_token> verification is implemented in app/edge/auth.py. - Recommended: HMAC-derived Base64 token (generate_edge_token(edge_agent_id, user_phone)) - Dev-only fallback: raw EDGE_SECRET (rejected when ENVIRONMENT == production)

{
  "chat_guid": "iMessage;-;+15551234567",
  "mode": "direct",
  "sender": "+15551234567",
  "text": "hey sage what’s the vibe",
  "timestamp": 1760572800,
  "participants": ["+15551234567"],
  "metadata": {
    "filter_reason": "direct_message",
    "was_redacted": false,
    "redacted_fields": []
  },
  "context": {}
}

Optional header: edge agent ID

If you have a stable relay ID, include it so the backend can correlate HTTP requests with the edge WebSocket connection: 

X-Edge-Agent-Id: edge_5551234567

Response

Response model: app/models/schemas.py::OrchestratorResponse

Typical shape: 

{
  "should_respond": true,
  "reply_bubbles": ["...", "..."],
  "reply_text": "...",
  "schedule_message": null
}

2) POST /orchestrator/message (Legacy)

Backend route: app/main.py
Schema: app/models/schemas.py::OrchestratorRequest

Authentication

If RELAY_WEBHOOK_SECRET is configured, the backend expects: 

Authorization: Bearer <relay_secret>

If RELAY_WEBHOOK_SECRET is unset, the endpoint logs a warning and is effectively unsecured (development only).

Request

{
  "chat_guid": "iMessage;-;+15551234567",
  "mode": "direct",
  "sender": "+15551234567",
  "text": "hello sage!",
  "timestamp": 1760572800,
  "participants": ["+15551234567"]
}

Common Errors

  • 401 Unauthorized: missing/invalid Authorization header
  • 422 Validation Error: wrong field types (e.g. timestamp not an int)
  • 429 Too Many Requests: rate limiting (legacy orchestrator endpoint)

Smoke Tests

Edge ingest

curl -X POST https://api.ikiro.ai/edge/message \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer <EDGE_TOKEN>' \\
  -H 'X-Edge-Agent-Id: edge_5551234567' \\
  -d '{\"chat_guid\":\"iMessage;-;+15551234567\",\"mode\":\"direct\",\"sender\":\"+15551234567\",\"text\":\"ping\",\"timestamp\":1760572800,\"participants\":[\"+15551234567\"]}'

Legacy ingest

curl -X POST https://api.ikiro.ai/orchestrator/message \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer <RELAY_WEBHOOK_SECRET>' \\
  -d '{\"chat_guid\":\"iMessage;-;+15551234567\",\"mode\":\"direct\",\"sender\":\"+15551234567\",\"text\":\"ping\",\"timestamp\":1760572800,\"participants\":[\"+15551234567\"]}'