Functions

Invoke function

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/ (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

POST

functions

{function_id}

invoke

curl --request POST \
  --url https://api.kapso.ai/platform/v1/functions/{function_id}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "weight": 5.5,
  "distance": 120,
  "service": "express"
}
'

{
  "cost": 24.75,
  "currency": "USD",
  "estimated_days": 2
}

Authorizations

X-API-Key

string

header

required

Path Parameters

function_id

string<uuid>

required

Function identifier

Body

application/json

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

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.

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.

List function secretsRetrieve all secret names configured for this function. Secret values are NEVER included in list responses for security. Secrets are injected as environment variables when your function executes. Use this endpoint to: - Audit which secrets are configured - Verify secret names before creating new ones - Check secret types (text, json, inherited) Important: If the function is not deployed, this endpoint returns an empty array. Secrets can only be managed for deployed functions. Secret values are only returned once when creating a secret via POST /functions/{id}/secrets. After creation, values cannot be retrieved - only the secret name and type are visible.

curl --request POST \
  --url https://api.kapso.ai/platform/v1/functions/{function_id}/invoke \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "weight": 5.5,
  "distance": 120,
  "service": "express"
}
'

{
  "cost": 24.75,
  "currency": "USD",
  "estimated_days": 2
}