# Functions

## List every platform function registered in the workspace

> List every platform function registered in the workspace.\
> \
> Permissions: \`\`Workspace.view\`\` (read role and above).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisteredFunctionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/RegisteredFunctionResponse"},"type":"array","title":"Items"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["items","count"],"title":"RegisteredFunctionListResponse"},"RegisteredFunctionResponse":{"properties":{"name":{"type":"string","title":"Name"},"function_type":{"type":"string","title":"Function Type"},"returns_kind":{"type":"string","title":"Returns Kind"},"description":{"type":"string","title":"Description","default":""},"when_to_use":{"type":"string","title":"When To Use","default":""},"parameters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parameters"},"sql_template":{"type":"string","title":"Sql Template"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"timeout_ms":{"type":"integer","title":"Timeout Ms","default":30000},"last_test_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test At"},"last_test_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Status"},"last_test_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Error"},"last_test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Test Duration Ms"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At"},"deployed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed By"}},"type":"object","required":["name","function_type","returns_kind","sql_template"],"title":"RegisteredFunctionResponse","description":"Single row from ``platform.functions``."}}},"paths":{"/v1/{workspace_id}/functions":{"get":{"tags":["Functions"],"summary":"List every platform function registered in the workspace","description":"List every platform function registered in the workspace.\n\nPermissions: ``Workspace.view`` (read role and above).","operationId":"list-functions","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisteredFunctionListResponse"}}}},"429":{"description":"Rate limited"}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get a registered platform function by name

> Resolve a function by name.\
> \
> Permissions: \`\`Workspace.view\`\` (read role and above).

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisteredFunctionResponse":{"properties":{"name":{"type":"string","title":"Name"},"function_type":{"type":"string","title":"Function Type"},"returns_kind":{"type":"string","title":"Returns Kind"},"description":{"type":"string","title":"Description","default":""},"when_to_use":{"type":"string","title":"When To Use","default":""},"parameters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parameters"},"sql_template":{"type":"string","title":"Sql Template"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"timeout_ms":{"type":"integer","title":"Timeout Ms","default":30000},"last_test_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test At"},"last_test_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Status"},"last_test_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Error"},"last_test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Test Duration Ms"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At"},"deployed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed By"}},"type":"object","required":["name","function_type","returns_kind","sql_template"],"title":"RegisteredFunctionResponse","description":"Single row from ``platform.functions``."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/functions/{function_name}":{"get":{"tags":["Functions"],"summary":"Get a registered platform function by name","description":"Resolve a function by name.\n\nPermissions: ``Workspace.view`` (read role and above).","operationId":"get-function","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisteredFunctionResponse"}}}},"404":{"description":"Function not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Deploy (validate + upsert) a platform function

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisteredFunction":{"properties":{"name":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"description":{"type":"string","maxLength":2048,"minLength":1,"title":"Description"},"when_to_use":{"type":"string","maxLength":2048,"title":"When To Use","default":""},"function_type":{"type":"string","enum":["sql","ai","udtf","python"],"title":"Function Type","default":"sql"},"returns":{"type":"string","enum":["table","scalar"],"title":"Returns","default":"table"},"returns_type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Returns Type","default":"string"},"parameters":{"items":{"$ref":"#/components/schemas/platform_lib__platform_functions__models__Parameter"},"type":"array","maxItems":32,"title":"Parameters"},"returns_columns":{"items":{"$ref":"#/components/schemas/ReturnColumn"},"type":"array","maxItems":32,"title":"Returns Columns"},"body":{"type":"string","maxLength":8192,"minLength":1,"title":"Body"},"timeout_ms":{"type":"integer","maximum":60000,"minimum":100,"title":"Timeout Ms","default":30000}},"additionalProperties":false,"type":"object","required":["name","description","body"],"title":"RegisteredFunction","description":"The authored shape of a platform function.\n\nIdentical wire format whether it's authored as a YAML file in the\nrepo or POSTed to ``/v1/{ws}/functions/deploy``. The deploy\npipeline validates this, derives the JSON Schema for the LLM tool\nspec, and INSERTs a row into ``platform.functions`` with the next\nmonotonic ``version`` per ``(workspace_id, name)``. For\n``python`` / ``udtf`` rows, deploy ALSO issues\n``CREATE OR REPLACE FUNCTION`` against the warehouse to materialize\nthe UC UDF."},"platform_lib__platform_functions__models__Parameter":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"minLength":1,"title":"Description"},"default":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"type":"null"}],"title":"Default"}},"additionalProperties":false,"type":"object","required":["name","type","description"],"title":"Parameter","description":"Typed declaration of one input parameter.\n\nFor SQL function types, ``name`` becomes the ``:name`` placeholder\nin the SQL template. For Python function types, ``name`` becomes\nthe positional argument name in ``def main(...)`` and the input\ncolumn name on the UC UDF signature.\n\nThe ``description`` propagates into the LLM tool spec (this is\nwhat Databricks' Agent Framework reads, and what Anthropic's\ntool-use spec exposes to the model). Missing descriptions\nsilently break tool selection — the registration layer rejects\nempty strings."},"ReturnColumn":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"pattern":"^[a-z][a-z0-9_]*$","title":"Name"},"type":{"type":"string","enum":["string","integer","number","boolean"],"title":"Type"},"description":{"type":"string","maxLength":512,"title":"Description","default":""}},"additionalProperties":false,"type":"object","required":["name","type"],"title":"ReturnColumn","description":"One column in a UDTF's output schema.\n\nUC ``RETURNS TABLE(<col1> <type1>, <col2> <type2>, ...)`` requires\ndeclaring the schema at deploy time. This list anchors that\nschema for ``function_type=udtf`` rows. ``name`` becomes the\ncolumn name in the result rows; ``type`` maps to a Databricks\nSQL type via the same ``ParameterType`` Literal we use for inputs."},"RegisteredFunctionResponse":{"properties":{"name":{"type":"string","title":"Name"},"function_type":{"type":"string","title":"Function Type"},"returns_kind":{"type":"string","title":"Returns Kind"},"description":{"type":"string","title":"Description","default":""},"when_to_use":{"type":"string","title":"When To Use","default":""},"parameters":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Parameters"},"sql_template":{"type":"string","title":"Sql Template"},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"timeout_ms":{"type":"integer","title":"Timeout Ms","default":30000},"last_test_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test At"},"last_test_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Status"},"last_test_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Test Error"},"last_test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Last Test Duration Ms"},"deployed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed At"},"deployed_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deployed By"}},"type":"object","required":["name","function_type","returns_kind","sql_template"],"title":"RegisteredFunctionResponse","description":"Single row from ``platform.functions``."}}},"paths":{"/v1/{workspace_id}/functions/{function_name}":{"put":{"tags":["Functions"],"summary":"Deploy (validate + upsert) a platform function","description":"Validate + upsert a platform function row.\n\nAtomic: validation + (python/udtf only) UC UDF materialization +\nupsert into ``platform.functions`` happen as one logical operation.\nRepeat deploys against the same ``(workspace, name)`` replace the\nrow in place and clear stale ``last_test_*`` telemetry.\n\nThe function name comes from the URL path; the request body's\n``name`` field must match or a 400 is raised. The URL is the\nauthoritative source.\n\nPermissions: admin, owner.","operationId":"deploy-function","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisteredFunction"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisteredFunctionResponse"}}}},"400":{"description":"URL function_name does not match body name"},"422":{"description":"Validation failure (read-only / bind / parity)"},"429":{"description":"Rate limited"}}}}}}
```

## Remove a registered platform function

> Remove a registered function row.\
> \
> Permissions: admin, owner.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/functions/{function_name}":{"delete":{"tags":["Functions"],"summary":"Remove a registered platform function","description":"Remove a registered function row.\n\nPermissions: admin, owner.","operationId":"delete-function","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"responses":{"204":{"description":"Successful Response"},"404":{"description":"Function not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Execute a registered platform function

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"InvokeRequest":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Caller arguments matching input_schema."}},"type":"object","title":"InvokeRequest","description":"Invoke a registered function with caller-supplied args."},"InvokeResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0}},"type":"object","title":"InvokeResponse"}}},"paths":{"/v1/{workspace_id}/functions/{function_name}/invoke":{"post":{"tags":["Functions"],"summary":"Execute a registered platform function","description":"Execute a registered function and return its rows.\n\nBound parameters are validated against the stored schema; ``ws_id``\nis auto-injected from the request context. Returns the executor's\nshaped response (``rows`` for ``returns=table``, scalar value for\n``returns=scalar``).\n\nPermissions: ``Workspace.view`` (read role and above). Read-only\nkeys are intentionally allowed — invocation runs a stored,\npre-validated SELECT against catalogs the workspace SP already has\nSELECT on; the gate on what can run is the deploy-time validator\n(read-only invariant), not the per-call permission.","operationId":"invoke-function","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeResponse"}}}},"404":{"description":"Function not found"},"422":{"description":"Bind validation failure"},"429":{"description":"Rate limited"}}}}}}
```

## Test invoke + persist last\_test\_\* telemetry on the row

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"InvokeRequest":{"properties":{"input":{"additionalProperties":true,"type":"object","title":"Input","description":"Caller arguments matching input_schema."}},"type":"object","title":"InvokeRequest","description":"Invoke a registered function with caller-supplied args."},"TestInvokeResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"row_count":{"type":"integer","title":"Row Count","default":0},"status":{"type":"string","title":"Status","default":"pass"},"error":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Error"},"test_duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Test Duration Ms"}},"type":"object","title":"TestInvokeResponse","description":"Response shape for ``POST /v1/{ws}/functions/{name}/test``.\n\nStructural superset of :class:`InvokeResponse`. Adds ``status`` and\n``error`` so the DC can render the executor's failure detail inline\nrather than a generic \"Invocation failed.\" The underlying invoke\nuses the same path; ``status`` / ``error`` are filled in by\n``service.test`` after catching any ``HTTPException`` (503) from the\nexecutor, so the route never bubbles a 5xx for a logical SQL\nfailure — it's still a 200 with ``status=fail`` so the caller can\nshow the message.\n\nInvariant (enforced by :func:`_check_error_when_fail`):\n``status == \"fail\" → error is not None and len(error) > 0``."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/functions/{function_name}/test":{"post":{"tags":["Functions"],"summary":"Test invoke + persist last_test_* telemetry on the row","description":"Test invoke — same as invoke + persists last_test_* on the row.\n\nReturns 200 with ``status=\"fail\"`` + populated ``error`` on\nexecution failure (instead of a 5xx) so the DC has a single\nhappy-path rendering.\n\nPermissions: admin, owner.","operationId":"test-function","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestInvokeResponse"}}}},"404":{"description":"Function not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.