Runs a function and records a REAL invocation.

POST /v1/functions/{name}/invoke

Runs a function and records a REAL invocation.

The answer is the invocation record whatever happened to it: 200 when the org's code ran clean, 502 when it ran and failed, 503 when this deployment has no sandbox to run code in. The record IS the evidence, so it rides the failure rather than being replaced by an error envelope.

Billing is two-part and both parts are prepaid-then-metered on the one shared meter: a flat per-invocation request fee, gated BEFORE any sandbox compute runs so an unfunded org gets 402 and nothing executes, and a usage-native GB-seconds compute debit taken after the run. Either is independently free when its fee is zero, so an operator can bill by request alone, by compute alone, or by both — and a zero request fee removes the balance gate with it.

A TRANSPORT failure is not charged: the sandbox being unreachable ran no billable compute. Code that ran and exited non-zero IS charged — that is a successful invocation of a failing program, not a billing failure.

When the sandbox is not configured on this deployment, a non-fleet function fails closed before anything is recorded — no execution and no fabricated output. Scoped to the caller's org; requires a validated principal.

Request

2 fields, body application/json (required).

Response

200 body — 6 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo functions invoke <name>

import { Configuration, FunctionsApi } from 'hanzoai';

const api = new FunctionsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postFunctionsByNameInvoke({ name: 'name', input: "<input>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = FunctionsApi(client).post_functions_by_name_invoke(name='name', input="<input>")

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

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

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

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

let result = functions_api::post_functions_by_name_invoke(&cfg, Default::default()).await?;

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

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

var result = new FunctionsApi(client).postFunctionsByNameInvoke();

curl -X POST https://api.hanzo.ai/v1/functions/<name>/invoke \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "input": "<input>"
     }'

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_functions"
         }
       }
     }'

Functions API · All Hanzo APIs · Interactive reference