---
title: "Invoke function"
method: POST
path: "/functions/{function_id}/invoke"
tags: ["Functions"]
---

# Invoke function

`POST /functions/{function_id}/invoke`

Execute a deployed serverless function with a custom JSON payload. The request body is forwarded directly to your function code.

Request payload structure is completely flexible - send any valid JSON that your function expects. Your function receives the payload as the request body and can parse it however needed.

Successful response behavior depends on `invoke_response_mode`:
- New functions default to `passthrough`, so Kapso forwards the function response body, success status code, and `Content-Type` directly
- Legacy wrapped functions can keep `wrapped`, which preserves the legacy API shape and returns successful JSON results under `data`

The function must be in 'deployed' status to be invoked. If the function is in 'draft' or 'error' status, the request will fail with 422 validation error.

Authentication:
- Private functions require `X-API-Key`
- Public Cloudflare functions (`public_endpoint=true`) can be invoked without an API key
- Private and unknown functions both return `404` from this route

Execution tracking:
- All invocations are tracked with timing and request/response data
- Failed invocations return an `invocation_id` for debugging
- Check function invocation history via GET /functions/{id} (extended view)

Error handling:
- Function execution errors are captured and returned with details
- Errors are truncated to 512 characters for storage
- Original error context is preserved in invocation record

## Request body

- FunctionInvokeRequest — Payload to send to the function. Structure is completely flexible - send any valid JSON that your function expects. The payload will be forwarded to your function as the request body.

## Response `200`

Function executed successfully. `wrapped` functions return successful JSON under `data`.
`passthrough` functions may also return other 2xx status codes and non-JSON content types depending on the function response.

- union
  - union — Successful invoke output for functions using `invoke_response_mode=passthrough`. Kapso forwards the upstream response body directly and preserves the upstream success status code and `Content-Type`.
    - object
    - unknown[]
      - unknown
    - string
    - number
    - boolean
  - FunctionInvokeWrappedResponse
    - `data` union, required — Successful invoke output for functions using `invoke_response_mode=wrapped`. Kapso preserves the legacy API shape by nesting successful JSON responses under `data`.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean

## Other responses

- `400` — Invalid JSON in request body
- `404` — Function not found, or private function is not accessible with the provided API key
- `422` — Function is not deployed or validation error
- `500` — Function execution failed

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)