# Functions

## List registered functions

> List all registered platform functions.\
> \
> Permissions: authenticated (any role).

```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":{"FunctionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FunctionDef"},"type":"array","title":"Items"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["items","count"],"title":"FunctionListResponse"},"FunctionDef":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"catalog":{"type":"string","maxLength":128,"title":"Catalog","default":"world"},"schema":{"type":"string","maxLength":128,"title":"Schema","default":"functions"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"returns_table":{"type":"boolean","title":"Returns Table","default":true},"enabled":{"type":"boolean","title":"Enabled","default":true},"function_type":{"type":"string","maxLength":32,"title":"Function Type","description":"sql | python | udtf | ai","default":"sql"}},"type":"object","required":["name"],"title":"FunctionDef","description":"A registered platform function."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}},"paths":{"/v1/{workspace_id}/functions":{"get":{"tags":["Functions"],"summary":"List registered functions","description":"List all registered platform functions.\n\nPermissions: authenticated (any role).","operationId":"list-functions","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionListResponse"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Register a new function

> Register a new platform function.\
> \
> The function must already exist in Databricks Unity Catalog.\
> This endpoint registers it so agents can discover and call it.\
> \
> 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":{"FunctionCreateRequest":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"catalog":{"type":"string","maxLength":128,"title":"Catalog","default":"world"},"schema":{"type":"string","maxLength":128,"title":"Schema","default":"functions"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"returns_table":{"type":"boolean","title":"Returns Table","default":true},"function_type":{"type":"string","maxLength":32,"title":"Function Type","default":"sql"}},"type":"object","required":["name"],"title":"FunctionCreateRequest","description":"Register a new function. Name must be unique within the workspace."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"FunctionDef":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"catalog":{"type":"string","maxLength":128,"title":"Catalog","default":"world"},"schema":{"type":"string","maxLength":128,"title":"Schema","default":"functions"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"returns_table":{"type":"boolean","title":"Returns Table","default":true},"enabled":{"type":"boolean","title":"Enabled","default":true},"function_type":{"type":"string","maxLength":32,"title":"Function Type","description":"sql | python | udtf | ai","default":"sql"}},"type":"object","required":["name"],"title":"FunctionDef","description":"A registered platform function."}}},"paths":{"/v1/{workspace_id}/functions":{"post":{"tags":["Functions"],"summary":"Register a new function","description":"Register a new platform function.\n\nThe function must already exist in Databricks Unity Catalog.\nThis endpoint registers it so agents can discover and call it.\n\nPermissions: admin, owner.","operationId":"create-function","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionDef"}}}},"409":{"description":"Function name already registered"},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}}}}
```

## Discover functions from Databricks UC catalog

> Discover available functions from the Databricks UC catalog.\
> \
> Queries \`\`INFORMATION\_SCHEMA.ROUTINES\`\` to find all functions with\
> a COMMENT clause. Shows which functions are already registered in\
> this workspace.\
> \
> 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":{"CatalogResponse":{"properties":{"functions":{"items":{"$ref":"#/components/schemas/CatalogFunctionDef"},"type":"array","title":"Functions"},"count":{"type":"integer","title":"Count","default":0},"catalog":{"type":"string","title":"Catalog","default":"world"},"schema":{"type":"string","title":"Schema","default":"functions"}},"type":"object","required":["functions"],"title":"CatalogResponse","description":"Response from catalog discovery."},"CatalogFunctionDef":{"properties":{"name":{"type":"string","title":"Name"},"data_type":{"type":"string","title":"Data Type","default":""},"comment":{"type":"string","title":"Comment","default":""},"registered":{"type":"boolean","title":"Registered","default":false}},"type":"object","required":["name"],"title":"CatalogFunctionDef","description":"A function discovered from the Databricks UC catalog."}}},"paths":{"/v1/{workspace_id}/functions/catalog":{"get":{"tags":["Functions"],"summary":"Discover functions from Databricks UC catalog","description":"Discover available functions from the Databricks UC catalog.\n\nQueries ``INFORMATION_SCHEMA.ROUTINES`` to find all functions with\na COMMENT clause. Shows which functions are already registered in\nthis workspace.\n\nPermissions: admin, owner.","operationId":"discover-catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResponse"}}}},"429":{"description":"Rate limited"},"503":{"description":"Agent engine unavailable"}}}}}}
```

## Auto-register all discovered catalog functions

> Auto-register all discovered catalog functions.\
> \
> Discovers functions from \`\`INFORMATION\_SCHEMA.ROUTINES\`\` and registers\
> any that aren't already registered in this workspace. Functions with\
> a COMMENT become tools — the COMMENT is the tool description.\
> \
> 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":{"FunctionListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/FunctionDef"},"type":"array","title":"Items"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["items","count"],"title":"FunctionListResponse"},"FunctionDef":{"properties":{"name":{"$ref":"#/components/schemas/NameString"},"catalog":{"type":"string","maxLength":128,"title":"Catalog","default":"world"},"schema":{"type":"string","maxLength":128,"title":"Schema","default":"functions"},"description":{"$ref":"#/components/schemas/DescriptionString","default":""},"input_schema":{"additionalProperties":true,"type":"object","title":"Input Schema"},"returns_table":{"type":"boolean","title":"Returns Table","default":true},"enabled":{"type":"boolean","title":"Enabled","default":true},"function_type":{"type":"string","maxLength":32,"title":"Function Type","description":"sql | python | udtf | ai","default":"sql"}},"type":"object","required":["name"],"title":"FunctionDef","description":"A registered platform function."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000}}},"paths":{"/v1/{workspace_id}/functions/sync":{"post":{"tags":["Functions"],"summary":"Auto-register all discovered catalog functions","description":"Auto-register all discovered catalog functions.\n\nDiscovers functions from ``INFORMATION_SCHEMA.ROUTINES`` and registers\nany that aren't already registered in this workspace. Functions with\na COMMENT become tools — the COMMENT is the tool description.\n\nPermissions: admin, owner.","operationId":"sync-catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionListResponse"}}}},"429":{"description":"Rate limited"},"503":{"description":"Agent engine unavailable"}}}}}}
```

## Execute an open-scope SQL query

> Execute an open-scope read-only SQL query via agent-engine.\
> \
> The SQL is validated to be read-only (SELECT/WITH only) and executed\
> on a Databricks serverless warehouse. Can query world model data\
> (\`\`lakebase\_production.world.\*\`\`) and analytics (\`\`billing.public.\*\`\`).\
> \
> Permissions: admin, owner (requires \`\`tools:test\`\` scope).

```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":{"QueryRequest":{"properties":{"sql":{"type":"string","maxLength":4000,"title":"Sql","description":"Read-only SQL SELECT statement"}},"type":"object","required":["sql"],"title":"QueryRequest","description":"Execute an open-scope SQL query."},"QueryResponse":{"properties":{"results":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Results"},"count":{"type":"integer","title":"Count","default":0},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","title":"QueryResponse"},"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/query":{"post":{"tags":["Functions"],"summary":"Execute an open-scope SQL query","description":"Execute an open-scope read-only SQL query via agent-engine.\n\nThe SQL is validated to be read-only (SELECT/WITH only) and executed\non a Databricks serverless warehouse. Can query world model data\n(``lakebase_production.world.*``) and analytics (``billing.public.*``).\n\nPermissions: admin, owner (requires ``tools:test`` scope).","operationId":"query-functions","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"},"503":{"description":"Agent engine unavailable"}}}}}}
```

## Remove a registered function

> Remove a registered function.\
> \
> This only removes the platform registration — the underlying\
> Databricks function is not affected.\
> \
> 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 function","description":"Remove a registered function.\n\nThis only removes the platform registration — the underlying\nDatabricks function is not affected.\n\nPermissions: admin, owner.","operationId":"delete-function","parameters":[{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Delete-Function"}}}},"404":{"description":"Function not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Test a function with sample input

> Test a registered function with sample input.\
> \
> Proxies to agent-engine's internal tool test endpoint.\
> \
> Permissions: admin, owner (requires \`\`tools:test\`\` scope).

```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":{"FunctionTestRequest":{"properties":{"input_params":{"additionalProperties":true,"type":"object","title":"Input Params"}},"type":"object","title":"FunctionTestRequest","description":"Test a function with sample input."},"FunctionTestResponse":{"properties":{"result":{"title":"Result"},"duration_ms":{"type":"number","title":"Duration Ms","default":0},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"function_name":{"type":"string","title":"Function Name","default":""}},"type":"object","title":"FunctionTestResponse"},"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 a function with sample input","description":"Test a registered function with sample input.\n\nProxies to agent-engine's internal tool test endpoint.\n\nPermissions: admin, owner (requires ``tools:test`` scope).","operationId":"test-function","parameters":[{"name":"function_name","in":"path","required":true,"schema":{"type":"string","title":"Function Name"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionTestRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionTestResponse"}}}},"404":{"description":"Function not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"},"503":{"description":"Agent engine unavailable"}}}}}}
```