---
title: "Invoke a function synchronously"
method: POST
path: "/functions/{id}/invoke"
tags: ["invoke"]
---

# Invoke a function synchronously

`POST /functions/{id}/invoke`

## Path parameters

- `id` string, uuid, required

## Headers

- `X-TensorWasm-Tenant` integer

## Request body

- InvokeRequest — Body of POST /functions/{id}/invoke (and the async sibling). Both fields are optional — an empty body or `{}` is the canonical no-args case, matching the pre-args wire contract. Unknown top-level fields are ignored for forward compatibility; malformed JSON surfaces as 400 invalid_json.
  - `export` string, nullable — Optional export-name override. When omitted (or null), the server tries `_start` first and falls back to `main`, matching the WASI command convention.
  - `args` union[] — Argument list forwarded to the executor's `call_export_with_args` path. Each element is converted to the closest-fitting wasm value type: integers in [-2^31, 2^31) become i32, larger integers become i64, non-integer numerics become f64. Strings / arrays / null / booleans are rejected as 400 invalid_args. f32 cannot be selected from JSON unambiguously — write a guest wrapper that demotes from f64 if you need it.
    - union
      - integer
      - number, double

## Response `200`

Invocation complete

- InvokeResult
  - `function_id` string, uuid, required — Server-assigned function identifier (UUIDv4).
  - `result` unknown, required

## Other responses

- `400` — Validation failure
- `401` — Missing or unrecognised bearer token
- `403` — Bearer token is not scoped to the requested tenant
- `404` — Function or job id is unknown
- `413` — Request body exceeded the 64 MiB cap enforced by axum's `DefaultBodyLimit::max`. Often rendered as a bare 413 with no body when the limit is hit during streaming.
- `429` — Per-token QPS + burst exceeded. The `Retry-After` header carries the wait in integer seconds (RFC 9110 §10.2.3).
- `500` — Underlying wasmtime or host failure
- `504` — Invocation exceeded its per-call deadline

---

[API](https://skmtc.dev/craton-co/apis/tensorwasm-http-api.md) · [All operations](https://skmtc.dev/craton-co/apis/tensorwasm-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/craton-co/tensorwasm-http-api/revisions/d363e13d8640/schema)