Replica-to-replica forward of one invocation to the pod holding the node's…

POST /v1/node/peer/invoke

A machine hop, not a caller-facing route. A node's socket lands on one replica while invocations land on any, so the replica that took the request forwards it here to the one that actually holds the node, and returns that answer as its own.

It authenticates with the shared peer token, compared in constant time, and carries no user identity at all. That is why the org arrives IN THE BODY here: the forwarding replica already derived it from a gateway-validated header, so the value is a fact being relayed rather than a claim being made. On any caller-facing route the same field would be a cross-tenant invoke primitive.

It fails closed on its own configuration: with no peer token set, or a half-wired cluster that has presence but no way to forward, it serves 503 and forwards nothing — an unauthenticated endpoint that takes an org from a body is precisely the hole. A missing or wrong token is 403, and the forwarded body is bounded on read.

Two things to get right. Its refusals are text/plain rather than the JSON every zip error uses, so a client decoding them as JSON will fail on the error path only. And an invocation that RAN but was denied still answers 200 here, carrying a stable error token in the JSON body — no such node, timeout, node gone, denied, failed — which the calling replica maps back onto the status codes a caller sees. Authorization already ran on this replica at the socket and is deliberately not repeated.

Request

The document declares no body for POST /v1/node/peer/invoke. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask the MCP door's describe for post_node_peer_invoke, which answers from the running route.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

import { Configuration, NodeApi } from 'hanzoai';

const api = new NodeApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postNodePeerInvoke();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import NodeApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = NodeApi(client).post_node_peer_invoke()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.NodeAPI.PostNodePeerInvoke(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, node_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = node_api::post_node_peer_invoke(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.NodeApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new NodeApi(client).postNodePeerInvoke();

curl -X POST https://api.hanzo.ai/v1/node/peer/invoke \
  -H "Authorization: Bearer $HANZO_API_KEY"

Node API · All Hanzo APIs · Interactive reference