/functions/{name}/invokeInvoke Function
Invokes the named function with a caller-supplied payload.
By default the call is synchronous: the response (200 OK) contains the function's return value under data plus meta fields including functionName, version, durationMs, and invocationId.
With background: true the call is stored and answered 202 with data.invocationId; the function runs afterwards at most once, and is never retried after it starts.
An accepted call can end without running: the invocation's status and reason say so.
A background invocation runs for at most 15 minutes.
It has no plain egress, and a credentialed send it makes can happen up to 15 minutes after the call was accepted.
Its status and result are read by that id, by the caller who started it, through GET /@{projectSlug}/functions/{name}/invocations/{invocationId} or the MCP get_invocation tool.
Errors:
404 K9O_FUNCTION_NOT_FOUNDfor absent or retired functions409 K9O_FUNCTION_NOT_READYwhile deploying422 K9O_FUNCTION_DEPLOYMENT_FAILEDon a failed deployment503 K9O_FUNCTION_MEMORY_EXCEEDEDwhen the function exceeds its tier memory limit504 K9O_FUNCTION_TIMEOUTon execution time exceeded422 K9O_FUNCTION_RUNTIME_ERRORon unhandled exception
| name * | path | The name of the function to call. A module's operation is named |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| payload | any | The input passed to the function, any JSON value. The function reads it as its request body. Default null. |
| approval | object | Runs a call that was held for approval and has since been approved: send the same function and the same A call parked for the platform to run ( |
| id * | string | The |
| bindingNonce * | string | The |
| approvalWindowSeconds | number | If the call is held for approval, how long approvers have to decide, in seconds. At least 60. It can only shorten the window, which stays within the project's maximum (and 72 hours for a parked call). |
| background | boolean | Set to true to run the call in the background: the response is 202 with an Default false, which runs it now and returns its result. |
| delegation | object | Run the call scoped to one end user, on the strength of a delegation token. Use at most one of |
| token * | string | A signed delegation token naming the end user ( The signature is what authorizes it. |
| invokeSessionId | string | A session id the token is bound to, used only to match the token to this call. |
| onBehalfOf | string | An end user id ( Your credential must hold an on-behalf-of grant. Use at most one of |
| confinedTo | string | An end user id ( Your credential must hold an Use at most one of |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 202 | Accepted | |
| 400 | K9O_INVALID_FIELD_VALUE | approvalWindowSeconds is not a whole number of seconds of at least 60 (a held call's window; above the project's maximum it is held to it). |
| 401 | K9O_INVALID_CREDENTIALS | Your credentials are missing or invalid; authenticate before invoking a function. |
| 403 | K9O_ACCESS_DENIED | Your account does not have sufficient permission to invoke functions on this project. |
| 403 | K9O_FORBIDDEN | An extension called by another extension (its token carries the hop marker) asked for a background invocation; one hop only, so it may not start an asynchronous dispatch. Answered before the 501. |
| 403 | K9O_FORBIDDEN | This call can't run in the background: the caller is an extension, a sandbox or playground session, or not a person or service token; the call carries an approval or a signed delegation; or the project isn't on platform-managed custody. Call the function without `background`. |
| 404 | K9O_FUNCTION_NOT_FOUND | No function with that name exists in this project, or it has been retired. |
| 409 | K9O_STATE_CONFLICT | The function changed while a background invocation was being accepted; nothing was queued. Retry. |
| 409 | K9O_FUNCTION_NOT_READY | The function exists but is still deploying; wait for deployment to complete before invoking. |
| 422 | K9O_FUNCTION_DEPLOYMENT_FAILED | The function's most recent deployment failed; redeploy the function before invoking. |
| 422 | K9O_FUNCTION_RUNTIME_ERROR | The function threw an unhandled exception during execution. |
| 422 | K9O_FUNCTION_MEMORY_EXCEEDED | The function exceeded its memory limit and was terminated. |
| 429 | K9O_RATE_LIMITED | This project already has the maximum number of background invocations waiting; `context.limit` names it. Retry once some have run. |
| 503 | K9O_ENVELOPE_KEK_UNAVAILABLE | The payload of a background invocation couldn't be sealed for storage; nothing was queued. Retry. |
| 504 | K9O_FUNCTION_TIMEOUT | The function exceeded its maximum execution time limit. |
| data * | any | What the function returned, parsed as JSON. Null when it returned nothing. Output that isn't JSON comes back as |
| meta * | any | Request metadata plus the invocation's: |
| data * | any | The function has not run yet: a background call was accepted, or the call is held or parked for approval. |
| One of: object | ||
| invocationId * | string | The id of the background invocation. Its outcome is recorded under this id. |
| or: object | ||
| approvalId * | string | The approval case the call waits on ( |
| status * | "pending_approval" | Always |
| payloadHash * | string | The SHA-256 (hex) binding this function version, its code and your payload to the approval. Approvers see it. |
| bindingNonce * | string | A secret you send back, with |
| functionVersion * | string | The function version that was approved for. A redeploy before the call runs voids the approval. |
| expiresAt * | string <date-time> | When the case expires if no one decides it. |
| or: object | ||
| approvalId * | string | The approval case the call waits on ( |
| status * | "pending_approval" | Always |
| payloadHash * | string | The SHA-256 (hex) binding this function version, its code and your payload to the approval. Approvers see it. |
| bindingNonce * | string | A secret you send back, with |
| functionVersion * | string | The function version that was approved for. A redeploy before the call runs voids the approval. |
| expiresAt * | string <date-time> | When the case expires if no one decides it. |
| callId * | string | The id to read the outcome by once the platform has run the call. The same value as |
| parked * | true | Always true: the platform runs this call itself once it is approved. |
| meta * | any | Request metadata. For a held or parked call, |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.functions.invoke('greet', {
payload: null,
background: false
})Showing example in TypeScript
{
"payload": null,
"background": false
}{}{
"data": {
"invocationId": "string"
}
}