CM AI Docking Port

A standardized entry point for AI agents into the CM Ecosystem — protocol version 0.1

This page documents an interface, not a product. CM (Channel Manager) instances run their own business logic for availability, pricing and reservations. The Docking Port does not duplicate that logic — it is a thin discovery and routing layer that lets any AI agent, speaking plain HTTP and JSON, find out what a CM instance can answer and how to ask.

What is the CM Ecosystem

Each CM installation is an independent node. A node may optionally participate in a decentralized network of other CM nodes ("the Ecosystem"). There is no central server that holds the whole network — each node knows only a small set of geographically relevant neighbours. A request entering through any one node's Docking Port can, within limits, be forwarded through that local network and aggregated back into a single answer.

What is Reception

Reception is the only endpoint an agent ever calls. It:

• accepts a structured request (the Request Envelope, below),
• answers from its own local data when it can,
• if useful and allowed by the request's limits, forwards the same request to nearby nodes,
• collects whatever comes back,
• and returns one aggregated, structured response (the Response Envelope).

This node's Reception:

POST /app/public/ai/reception.php
Content-Type: application/json

status: live — Reception answers local availability queries (depth 0). Multi-node forwarding is not built yet.

How to discover this node

Start with the machine-readable manifest:

GET /.well-known/cm-ai-docking-port.json
GET /app/public/ai/manifest.json

It describes this node's identity, location, capabilities, and the Reception endpoint. Example (this node):

{
  "protocol": "CM-AI-Docking-Port",
  "version": "0.1",
  "service": {
    "name": "CM Ecosystem Reception",
    "type": "ai-entry-point",
    "node_id": "CM-AI-DEMO-058",
    "location": {
      "label": "Lancovo / Radovljica area (Demo 58)",
      "lat": 46.34,
      "lon": 14.17
    }
  },
  "reception": {
    "method": "POST",
    "endpoint": "/app/public/ai/reception.php",
    "content_type": "application/json"
  }
}

Request Envelope

Every request sent to Reception uses this shape:

{
  "protocol": "CM-AI-Docking-Port",
  "version": "0.1",
  "request_id": "req-2026-08-10-abc123",
  "request_expiry": "2026-08-10T12:00:00Z",
  "origin": "ai-agent",
  "target": {
    "location": { "lat": 46.05, "lon": 14.50, "label": "Ljubljana" },
    "radius_km": 30
  },
  "query": {
    "type": "availability",
    "from": "2026-08-10",
    "to": "2026-08-16",
    "guests": 2,
    "units": null
  },
  "limits": {
    "max_depth": 2,
    "max_distance_km": 40,
    "max_results": 10
  },
  "visited": []
}

• request_id — unique per request; lets a node detect duplicates.
• request_expiry — required on every request. Reception currently checks only that it is present; its format and expiry semantics are not yet enforced.
• target.location — the place the agent is actually asking about. This is not necessarily where the agent knocked. An agent may enter through this node and ask about a different city; Reception routes toward the target, not toward itself.
• visited — filled in by Reception as the request travels, never by the agent. Prevents routing loops.
• limits — the agent's own bounds on how far and how wide the search may go.

Response Envelope

Reception always answers with one aggregated response, never raw internal API output:

{
  "protocol": "CM-AI-Docking-Port",
  "version": "0.1",
  "request_id": "req-2026-08-10-abc123",
  "ok": true,
  "partial": false,
  "search_meta": {
    "entry_node": "CM-AI-DEMO-058",
    "target_location": { "lat": 46.05, "lon": 14.50, "label": "Ljubljana" },
    "nodes_queried": 1,
    "nodes_reached": 1,
    "max_depth_used": 0,
    "max_depth_limit": 2
  },
  "results": [
    {
      "node_id": "CM-AI-DEMO-058",
      "depth": 0,
      "source": "local_availability_api",
      "freshness": { "generated_at": "2026-09-29T18:00:00+00:00" },
      "data": { "...": "raw output of this node's own availability API, unmodified" }
    }
  ],
  "errors": []
}

data inside each result is the untouched output of that node's own business API — Reception wraps it with provenance (which node answered, at what depth, how fresh) but never reinterprets it. If part of the network was unreachable, partial is true and the response says so plainly; a partial search is never presented as a complete one.

Capabilities of this node

Every capability declares whether it changes anything (side_effect) and whether it requires explicit consent. This first version is read/discovery only — nothing an agent does through Reception creates a booking, a block, or any other write.

Limits

Rules for agents

• Always talk to Reception. Never call this node's internal APIs directly, even if you can guess the URL.
• Never contact other CM nodes yourself — Reception does that on your behalf.
• The entry point and the search target are separate concepts. Ask for what you actually want, wherever you knocked.
• The existence of a node does not imply access to everything it holds — discovery, availability, and private data are different tiers.
• This is a read/discovery protocol. Do not assume any request can change data.

How this grows

New capabilities are added to the manifest and the protocol — not by building a new AI system on top of CM. CM stays the source of truth; the Docking Port stays a thin, generic HTTP/JSON door that any AI provider can use without a CM-specific plugin.