Skip to main content
POST/functions/{name}/invoke

Invoke 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_FOUND for absent or retired functions
  • 409 K9O_FUNCTION_NOT_READY while deploying
  • 422 K9O_FUNCTION_DEPLOYMENT_FAILED on a failed deployment
  • 503 K9O_FUNCTION_MEMORY_EXCEEDED when the function exceeds its tier memory limit
  • 504 K9O_FUNCTION_TIMEOUT on execution time exceeded
  • 422 K9O_FUNCTION_RUNTIME_ERROR on unhandled exception
Parameters
name *path

The name of the function to call.

A module's operation is named <module>:<operation>.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
payloadany

The input passed to the function, any JSON value.

The function reads it as its request body.

Default null.

approvalobject

Runs a call that was held for approval and has since been approved: send the same function and the same payload again with this.

A call parked for the platform to run (parked: true) can't be redeemed this way.

id *string

The approvalId from the held call's 202 response (apr_...).

bindingNonce *string

The bindingNonce from the same 202 response.

approvalWindowSecondsnumber

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).

backgroundboolean

Set to true to run the call in the background: the response is 202 with an invocationId and the function runs later.

Default false, which runs it now and returns its result.

delegationobject

Run the call scoped to one end user, on the strength of a delegation token.

Use at most one of delegation, onBehalfOf and confinedTo.

token *string

A signed delegation token naming the end user (sub) the call acts for and the acting party (act).

The signature is what authorizes it.

invokeSessionIdstring

A session id the token is bound to, used only to match the token to this call.

onBehalfOfstring

An end user id (eu_...) whose data the call reads, for a background or system call with no end-user token.

Your credential must hold an on-behalf-of grant.

Use at most one of delegation, onBehalfOf and confinedTo.

confinedTostring

An end user id (eu_...) to confine the call to: it may read and write only that user's rows.

Your credential must hold an invoke_confined_to grant.

Use at most one of delegation, onBehalfOf and confinedTo.

Responses
HTTPK9O CodeDescription
200Success
202Accepted
400K9O_INVALID_FIELD_VALUEapprovalWindowSeconds 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).
401K9O_INVALID_CREDENTIALSYour credentials are missing or invalid; authenticate before invoking a function.
403K9O_ACCESS_DENIEDYour account does not have sufficient permission to invoke functions on this project.
403K9O_FORBIDDENAn 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.
403K9O_FORBIDDENThis 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`.
404K9O_FUNCTION_NOT_FOUNDNo function with that name exists in this project, or it has been retired.
409K9O_STATE_CONFLICTThe function changed while a background invocation was being accepted; nothing was queued. Retry.
409K9O_FUNCTION_NOT_READYThe function exists but is still deploying; wait for deployment to complete before invoking.
422K9O_FUNCTION_DEPLOYMENT_FAILEDThe function's most recent deployment failed; redeploy the function before invoking.
422K9O_FUNCTION_RUNTIME_ERRORThe function threw an unhandled exception during execution.
422K9O_FUNCTION_MEMORY_EXCEEDEDThe function exceeded its memory limit and was terminated.
429K9O_RATE_LIMITEDThis project already has the maximum number of background invocations waiting; `context.limit` names it. Retry once some have run.
503K9O_ENVELOPE_KEK_UNAVAILABLEThe payload of a background invocation couldn't be sealed for storage; nothing was queued. Retry.
504K9O_FUNCTION_TIMEOUTThe function exceeded its maximum execution time limit.
Response body (200)
data *any

What the function returned, parsed as JSON.

Null when it returned nothing.

Output that isn't JSON comes back as {"_binary_base64": "<base64>"}.

meta *any

Request metadata plus the invocation's: functionName, version, tier, runtime, durationMs, invocationId, artifactBytes, resultBytes, fuelConsumed and executor.

Response body (202)
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 (apr_...).

status *"pending_approval"

Always pending_approval: the function has not run.

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 approvalId, to run the call once it is approved.

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 (apr_...).

status *"pending_approval"

Always pending_approval: the function has not run.

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 approvalId, to run the call once it is approved.

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 approvalId.

parked *true

Always true: the platform runs this call itself once it is approved.

meta *any

Request metadata.

For a held or parked call, approval.status is pending_approval.

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

Request example
{
  "payload": null,
  "background": false
}
Response example (200)
{}
Response example (202)
{
  "data": {
    "invocationId": "string"
  }
}

More in Compute & Automation