Platform Functions
Deploy, invoke, version, promote, and roll back registered platform functions.
Platform functions are registered, parameterized read queries that the agent calls mid-conversation to retrieve live data. The API provides endpoints for the full function lifecycle: deploy, invoke, test, promote, and rollback.
Concepts
Versions
Every deploy creates a new immutable version. Versions are numbered monotonically per function name within a workspace (v1, v2, v3, ...). Prior versions are never modified.
Aliases
Functions are resolved through aliases, not raw version numbers:
latest
Automatically rebound on every deploy
staging
Manually promoted for pre-production validation
production
Manually promoted for production traffic
Parameter Types
string
Text value (also covers UUIDs, dates, datetimes)
integer
Whole number
number
Floating-point number
boolean
True or false
Function Types
sql
Parameterized query against entity and analytical data
ai
Query wrapping an AI classification or extraction step
udtf
User-defined table function (reserved)
python
Custom logic authored externally (reserved)
Return Kinds
table
Returns a list of rows (list of objects)
scalar
Returns a single value (first column of first row)
Endpoints
Deploy a Function
Validates and registers a new function version. Automatically rebinds the latest alias to the new version.
Request body:
name
string
Yes
Function name. Lowercase letters, digits, and underscores. 1-128 characters. Must start with a letter.
description
string
Yes
What the function does. 1-2048 characters. Surfaced to the agent for tool selection.
when_to_use
string
No
Guidance for when the agent should select this function. Max 2048 characters.
function_type
string
No
One of sql, ai, udtf, python. Default: sql.
returns
string
No
One of table, scalar. Default: table.
parameters
array
No
List of parameter declarations (max 32). See Parameter object below.
sql
string
Yes
Query template with :name-style bind placeholders. 1-8192 characters.
timeout_ms
integer
No
Execution timeout in milliseconds. 100-60000. Default: 30000.
examples
array
No
Example calls (max 8). See Example object below.
Parameter object:
name
string
Yes
Parameter name. Lowercase letters, digits, underscores. Must start with a letter. 1-64 characters.
type
string
Yes
One of string, integer, number, boolean.
description
string
Yes
What this parameter controls. 1-512 characters.
required
boolean
No
Whether the caller must supply this parameter. Default: true.
default
string, integer, number, or boolean
No
Default value when the caller omits this parameter. Must match declared type.
Example object:
input
object
Yes
Example caller arguments.
output
any
Yes
Expected output.
description
string
No
What this example demonstrates.
Response: FunctionVersion object (see below).
Errors:
409
Concurrent deploy raced at the same version
422
Validation failure (read-only violation, parameter mismatch, missing workspace binding)
429
Rate limited
Validation rules applied at deploy time:
Query must be a read-only operation. Mutation keywords are rejected.
Every declared parameter must be referenced in the query template.
Every bind placeholder in the query must have a matching parameter declaration.
Queries against workspace-scoped data must include the workspace binding (auto-injected at execution time).
Default values must match their declared parameter type.
List Functions
Returns the latest version of every registered function in the workspace.
Response:
items
array
List of FunctionVersion objects
count
integer
Total number of functions
List Function Versions
Returns all versions of a function, newest first.
Response:
items
array
List of FunctionVersion objects
count
integer
Total number of versions
Get Function Version
Resolves a function name and alias to a specific version.
Query parameters:
alias
string
latest
One of latest, staging, production
Response: FunctionVersion object.
Invoke a Function
Executes a registered function with caller-supplied arguments.
Request body:
input
object
No
Caller arguments matching the function's input schema. Default: empty object.
alias
string
No
Alias to resolve. One of latest, staging, production. Default: latest.
Response:
result
any
Query result. For table functions: list of row objects. For scalar functions: single value.
duration_ms
number
Execution time in milliseconds
row_count
integer
Number of rows returned
version
integer
Version that was executed
Errors:
404
Function not found at the specified alias
422
Bind validation failure (missing required argument, unknown argument, type mismatch)
429
Rate limited
503
Query execution backend unavailable
Notes:
Workspace isolation is automatically applied. The workspace identifier is injected as a bind parameter at execution time.
Unknown arguments (not declared in the function's parameter list) are rejected.
Missing optional parameters use their declared default value, or null if no default is set.
Read-only keys (view permission) are allowed to invoke functions.
Test a Function
Same as invoke, but also persists test results (pass/fail status, error details, execution duration) on the version row for dashboard display.
Request body: Same as Invoke.
Response: Same as Invoke, plus:
status
string
pass or fail
error
string or null
Error message if status is fail
test_duration_ms
integer
Total test duration including overhead
Permissions: Requires write access (admin or owner role).
Promote a Function
Rebinds an alias to a specific version.
Request body:
alias
string
Yes
One of latest, staging, production
version
integer
Yes
Version number to bind the alias to. Must be >= 1.
Response:
name
string
Function name
alias
string
Alias that was rebound
version
integer
Version the alias now points to
Errors:
404
Function or version not found
429
Rate limited
Permissions: Requires write access (admin or owner role).
Rollback a Function
Rebinds both latest and production aliases to a prior version. The staging alias is not affected.
Request body:
version
integer
Yes
Prior version to roll back to. Must be >= 1.
Response:
name
string
Function name
rolled_back_to_version
integer
Version that latest and production now point to
Errors:
404
Function or version not found
429
Rate limited
Permissions: Requires write access (admin or owner role).
FunctionVersion Object
name
string
Function name
version
integer
Version number
function_type
string
sql, ai, udtf, or python
returns_kind
string
table or scalar
description
string
Function description
when_to_use
string
Guidance for agent tool selection
parameters
array
Parameter declarations
sql_template
string
Query template with bind placeholders
input_schema
object
JSON Schema derived from parameters. Used by the agent for tool selection.
examples
array
Example calls
timeout_ms
integer
Execution timeout in milliseconds
source_path
string or null
Source file path (for repository-managed functions)
source_hash
string or null
Source content hash (for repository-managed functions)
last_test_at
string or null
ISO timestamp of last test execution
last_test_status
string or null
pass or fail
last_test_error
string or null
Error message from last test
last_test_duration_ms
integer or null
Duration of last test in milliseconds
deployed_at
string or null
ISO timestamp of deployment
deployed_by
string or null
ID of the API key that deployed this version
Permissions
Deploy
Workspace.update (admin, owner)
List, Get, Invoke
Workspace.view (read and above)
Test
Workspace.update (admin, owner)
Promote
Workspace.update (admin, owner)
Rollback
Workspace.update (admin, owner)
Last updated
Was this helpful?