Hybrid Canvas API Calls

Hybrid Canvas API Calls

This page documents the current behavior of canvas context exchange.

Current Runtime Mode

1. BFF pushes summary context to engine on chat/stream calls.
2. BFF also forwards optional canvas_profile data.
3. Internal pull endpoint exists (/api/internal/canvas/context) with strict auth.
4. Current engine code does not actively call the internal pull endpoint yet.

A. Push Contract (BFF -> Engine)

Applied to:

• POST /api/v1/chat
• POST /api/v1/chat/stream

Forwarded metadata shape (simplified):

{
  "metadata": {
    "knowledge_search": true,
    "attached_document_ids": ["doc_uuid"],
    "canvas_context": {
      "mode": "summary",
      "summary": {
        "nodeCount": 48,
        "byType": {
          "strategy_item": 22
        },
        "byStatus": {
          "approve": 18,
          "reject": 4,
          "pending": 26
        }
      },
      "context_ref": {
        "project_id": "project_uuid",
        "thread_id": "thread_uuid",
        "agent_id": "strategy",
        "revision": "f84ab409f6bda6da"
      }
    },
    "canvas_profile": {}
  }
}

Notes:

• Summary revision is derived from stable summary data hash.
• BFF normalizes status keys to approve, reject, pending.

B. Optional Pull Contract (Engine -> BFF Internal)

Route:

• GET /api/internal/canvas/context

Required headers:

• Authorization: Bearer <INTERNAL_ENGINE_TOKEN>
• X-Contract-Version: 2026-02
• X-User-Id: <user_uuid>
• X-Project-Id: <project_uuid>
• X-Thread-Id: <thread_uuid>

Required query:

• agentId
• projectId
• threadId

Optional query:

• revision
• maxNodes
• includeContent
• includeRelationships
• framework

Response shape:

{
  "success": true,
  "data": {
    "canvas_profile": {},
    "canvas_context": {
      "summary": {},
      "nodes": [],
      "relationships": {}
    }
  },
  "meta": {
    "revision": "f84ab409f6bda6da",
    "contractVersion": "2026-02"
  }
}

C. Error Semantics

• 401: missing or invalid internal token.
• 400: missing trusted claims or contract version mismatch.
• 403: trusted claim scope and query scope mismatch.
• 500: internal server/runtime failure.

D. Implementation References

• kobi-ai/app/api/ai/_proxy.js
• kobi-ai/app/api/internal/canvas/context/route.js
• kobi-ai/app/api/_auth.js
• kobi-agent-service/api/internal_contract.py