Functions

List every platform function registered in the workspace

get

List every platform function registered in the workspace.

Permissions: Workspace.view (read role and above).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

countintegerRequired

429

Rate limited

get/v1/{workspace_id}/functions

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/functions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "function_type": "text",
      "returns_kind": "text",
      "description": "",
      "when_to_use": "",
      "parameters": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "sql_template": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "examples": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "timeout_ms": 30000,
      "last_test_at": "text",
      "last_test_status": "text",
      "last_test_error": "text",
      "last_test_duration_ms": 1,
      "deployed_at": "text",
      "deployed_by": "text"
    }
  ],
  "count": 1
}

Get a registered platform function by name

get

Resolve a function by name.

Permissions: Workspace.view (read role and above).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Responses

200

Successful Response

application/json

Single row from platform.functions.

namestringRequired

function_typestringRequired

returns_kindstringRequired

descriptionstringOptionalDefault: ""

when_to_usestringOptionalDefault: ""

sql_templatestringRequired

timeout_msintegerOptionalDefault: 30000

last_test_atstring · nullableOptional

last_test_statusstring · nullableOptional

last_test_errorstring · nullableOptional

last_test_duration_msinteger · nullableOptional

deployed_atstring · nullableOptional

deployed_bystring · nullableOptional

404

Function not found

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "function_type": "text",
  "returns_kind": "text",
  "description": "",
  "when_to_use": "",
  "parameters": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "sql_template": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "examples": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "timeout_ms": 30000,
  "last_test_at": "text",
  "last_test_status": "text",
  "last_test_error": "text",
  "last_test_duration_ms": 1,
  "deployed_at": "text",
  "deployed_by": "text"
}

Deploy (validate + upsert) a platform function

put

Validate + upsert a platform function row.

Atomic: validation + (python/udtf only) UC UDF materialization + upsert into platform.functions happen as one logical operation. Repeat deploys against the same (workspace, name) replace the row in place and clear stale last_test_* telemetry.

The function name comes from the URL path; the request body's name field must match or a 400 is raised. The URL is the authoritative source.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

The authored shape of a platform function.

Identical wire format whether it's authored as a YAML file in the repo or POSTed to /v1/{ws}/functions/deploy. The deploy pipeline validates this, derives the JSON Schema for the LLM tool spec, and INSERTs a row into platform.functions with the next monotonic version per (workspace_id, name). For python / udtf rows, deploy ALSO issues CREATE OR REPLACE FUNCTION against the warehouse to materialize the UC UDF.

namestring · min: 1 · max: 128RequiredPattern: ^[a-z][a-z0-9_]*$

descriptionstring · min: 1 · max: 2048Required

when_to_usestring · max: 2048OptionalDefault: ""

function_typestring · enumOptionalDefault: sqlPossible values:

returnsstring · enumOptionalDefault: tablePossible values:

returns_typestring · enumOptionalDefault: stringPossible values:

bodystring · min: 1 · max: 8192Required

timeout_msinteger · min: 100 · max: 60000OptionalDefault: 30000

Responses

200

Successful Response

application/json

Single row from platform.functions.

namestringRequired

function_typestringRequired

returns_kindstringRequired

descriptionstringOptionalDefault: ""

when_to_usestringOptionalDefault: ""

sql_templatestringRequired

timeout_msintegerOptionalDefault: 30000

last_test_atstring · nullableOptional

last_test_statusstring · nullableOptional

last_test_errorstring · nullableOptional

last_test_duration_msinteger · nullableOptional

deployed_atstring · nullableOptional

deployed_bystring · nullableOptional

400

URL function_name does not match body name

422

Validation failure (read-only / bind / parity)

429

Rate limited

put/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 397

{
  "name": "text",
  "description": "text",
  "when_to_use": "",
  "function_type": "sql",
  "returns": "table",
  "returns_type": "string",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "returns_columns": [
    {
      "name": "text",
      "type": "string",
      "description": ""
    }
  ],
  "body": "text",
  "timeout_ms": 30000,
  "examples": [
    {
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": null,
      "description": ""
    }
  ]
}

{
  "name": "text",
  "function_type": "text",
  "returns_kind": "text",
  "description": "",
  "when_to_use": "",
  "parameters": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "sql_template": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "examples": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "timeout_ms": 30000,
  "last_test_at": "text",
  "last_test_status": "text",
  "last_test_error": "text",
  "last_test_duration_ms": 1,
  "deployed_at": "text",
  "deployed_by": "text"
}

Remove a registered platform function

delete

Remove a registered function row.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Responses

204

Successful Response

No content

404

Function not found

422

Validation Error

application/json

429

Rate limited

delete/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Execute a registered platform function

post

Execute a registered function and return its rows.

Bound parameters are validated against the stored schema; ws_id is auto-injected from the request context. Returns the executor's shaped response (rows for returns=table, scalar value for returns=scalar).

Permissions: Workspace.view (read role and above). Read-only keys are intentionally allowed — invocation runs a stored, pre-validated SELECT against catalogs the workspace SP already has SELECT on; the gate on what can run is the deploy-time validator (read-only invariant), not the per-call permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

404

Function not found

422

Bind validation failure

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/invoke

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/functions/{function_name}/invoke HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0
}

Test invoke + persist last_test_* telemetry on the row

post

Test invoke — same as invoke + persists last_test_* on the row.

Returns 200 with status="fail" + populated error on execution failure (instead of a 5xx) so the DC has a single happy-path rendering.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

Response shape for POST /v1/{ws}/functions/{name}/test.

Structural superset of :class:InvokeResponse. Adds status and error so the DC can render the executor's failure detail inline rather than a generic "Invocation failed." The underlying invoke uses the same path; status / error are filled in by service.test after catching any HTTPException (503) from the executor, so the route never bubbles a 5xx for a logical SQL failure — it's still a 200 with status=fail so the caller can show the message.

Invariant (enforced by :func:_check_error_when_fail): status == "fail" → error is not None and len(error) > 0.

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

statusstringOptionalDefault: pass

errorstring · max: 2000 · nullableOptional

test_duration_msinteger · nullableOptional

404

Function not found

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/test

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/functions/{function_name}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0,
  "status": "pass",
  "error": "text",
  "test_duration_ms": 1
}