From 5d9c9d62a1b2debc78548f5ba9d8c90dfb84f5b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 21 May 2026 09:11:25 +0000 Subject: [PATCH 1/2] Add docs for tool auto-execution and Smart Tables API **Tool Registry auto-execution (app PR #917)** - Add ToolExecutionConfig and ToolExecutionRunResult schemas to openapi.json - Add execution and description fields to POST /api/public/v2/tool-registry (create tool) - Add execution and description fields to GET /api/public/v2/tool-registry/{identifier} response - Add POST /api/public/v2/tool-registry/{identifier}/versions endpoint (create version, with execution field) - Add POST /api/public/v2/tool-registry/{identifier}/test-execute endpoint - Add reference pages for both new endpoints - Add features/tool-registry/auto-execution.mdx guide - Register auto-execution page in docs.json navigation **Smart Tables public API (app PR #932)** - Add SmartTable, SmartSheet, SmartColumn, SmartCell, and SmartTableImportOperation schemas to openapi.json - Add all core Smart Tables public API endpoints (/api/public/v2/tables + sheets, columns, rows, cells sub-resources) - Create reference pages for all 18 new Smart Tables endpoints - Register Smart Tables reference group in docs.json navigation https://claude.ai/code/session_01Gomnn5WphRge7nVT8BbMKr --- docs.json | 29 +- features/tool-registry/auto-execution.mdx | 93 + openapi.json | 2498 ++++++++++++++++- reference/table-sheet-cells-get.mdx | 8 + .../table-sheet-cells-recalculate-batch.mdx | 8 + reference/table-sheet-cells-recalculate.mdx | 6 + reference/table-sheet-cells-update.mdx | 8 + reference/table-sheet-columns-create.mdx | 8 + reference/table-sheet-columns-list.mdx | 10 + reference/table-sheet-columns-update.mdx | 8 + reference/table-sheet-rows-add.mdx | 8 + reference/table-sheet-rows-list.mdx | 10 + reference/table-sheets-create.mdx | 9 + reference/table-sheets-get-operation.mdx | 6 + reference/table-sheets-get.mdx | 6 + reference/table-sheets-list.mdx | 6 + reference/table-sheets-update.mdx | 6 + reference/tables-create.mdx | 8 + reference/tables-get.mdx | 6 + reference/tables-list.mdx | 6 + reference/tables-update.mdx | 6 + reference/tool-registry-create-version.mdx | 8 + reference/tool-registry-test-execute.mdx | 10 + 23 files changed, 2748 insertions(+), 23 deletions(-) create mode 100644 features/tool-registry/auto-execution.mdx create mode 100644 reference/table-sheet-cells-get.mdx create mode 100644 reference/table-sheet-cells-recalculate-batch.mdx create mode 100644 reference/table-sheet-cells-recalculate.mdx create mode 100644 reference/table-sheet-cells-update.mdx create mode 100644 reference/table-sheet-columns-create.mdx create mode 100644 reference/table-sheet-columns-list.mdx create mode 100644 reference/table-sheet-columns-update.mdx create mode 100644 reference/table-sheet-rows-add.mdx create mode 100644 reference/table-sheet-rows-list.mdx create mode 100644 reference/table-sheets-create.mdx create mode 100644 reference/table-sheets-get-operation.mdx create mode 100644 reference/table-sheets-get.mdx create mode 100644 reference/table-sheets-list.mdx create mode 100644 reference/table-sheets-update.mdx create mode 100644 reference/tables-create.mdx create mode 100644 reference/tables-get.mdx create mode 100644 reference/tables-list.mdx create mode 100644 reference/tables-update.mdx create mode 100644 reference/tool-registry-create-version.mdx create mode 100644 reference/tool-registry-test-execute.mdx diff --git a/docs.json b/docs.json index 6ed8d88..9fe0d2f 100644 --- a/docs.json +++ b/docs.json @@ -100,7 +100,8 @@ "pages": [ "features/tool-registry/overview", "features/tool-registry/using-in-prompts", - "features/tool-registry/save-inline-to-registry" + "features/tool-registry/save-inline-to-registry", + "features/tool-registry/auto-execution" ], "icon": "wrench" }, @@ -304,11 +305,37 @@ "reference/tool-registry-list", "reference/tool-registry-get", "reference/tool-registry-create", + "reference/tool-registry-create-version", + "reference/tool-registry-test-execute", "reference/external-ids-tool-registry-attach", "reference/external-ids-tool-registry-list", "reference/external-ids-tool-registry-delete" ] }, + { + "group": "Smart Tables", + "tag": "New", + "pages": [ + "reference/tables-create", + "reference/tables-list", + "reference/tables-get", + "reference/tables-update", + "reference/table-sheets-list", + "reference/table-sheets-create", + "reference/table-sheets-get-operation", + "reference/table-sheets-get", + "reference/table-sheets-update", + "reference/table-sheet-columns-list", + "reference/table-sheet-columns-create", + "reference/table-sheet-columns-update", + "reference/table-sheet-rows-list", + "reference/table-sheet-rows-add", + "reference/table-sheet-cells-get", + "reference/table-sheet-cells-update", + "reference/table-sheet-cells-recalculate", + "reference/table-sheet-cells-recalculate-batch" + ] + }, { "group": "Unified Registry", "pages": [ diff --git a/features/tool-registry/auto-execution.mdx b/features/tool-registry/auto-execution.mdx new file mode 100644 index 0000000..bd868dd --- /dev/null +++ b/features/tool-registry/auto-execution.mdx @@ -0,0 +1,93 @@ +--- +title: "Auto-Execution" +icon: "bolt" +--- + +Auto-execution lets you attach Python or JavaScript code directly to a Tool Registry entry. When the LLM calls the tool, PromptLayer automatically runs your code in a secure sandbox, feeds the result back to the model, and continues the conversation — all without writing any client-side loop. + +## How it works + +1. A tool version stores a function schema *and* optional execution code (Python or JavaScript). +2. During inference — in the Playground, via the Prompt Registry, or through evaluations — PromptLayer detects tool calls where an executable version is selected. +3. The platform extracts the function arguments from the LLM response, runs the code, and appends the result as a `tool` message. +4. The LLM receives the result and continues. The loop repeats until the model stops calling executable tools, or until the iteration limit is reached. + +Each LLM call in the loop is logged as its own request, so the full trace is visible in your request history. + +## Writing execution code + +Your code must define a function whose name matches the `name` field in the tool's function schema. + +**Python example** + +```python +def get_weather(location: str) -> dict: + import urllib.request, json + url = f"https://wttr.in/{location}?format=j1" + with urllib.request.urlopen(url) as resp: + data = json.load(resp) + return {"temperature": data["current_condition"][0]["temp_C"], "unit": "C"} +``` + +**JavaScript example** + +```javascript +async function get_weather(location) { + const resp = await fetch(`https://wttr.in/${location}?format=j1`); + const data = await resp.json(); + return { temperature: data.current_condition[0].temp_C, unit: "C" }; +} +``` + +The function receives the LLM's tool call arguments as keyword arguments (Python) or an object (JavaScript). Whatever you return is serialised to JSON and sent back to the model. + +## Adding execution code in the UI + +1. Open a tool in the Tool Registry. +2. Click **Edit → New Version**. +3. Switch to the **Execution** tab next to the schema editor. +4. Write your Python or JavaScript function. +5. Use **Test Run** to verify it works before saving. + + + Tool registry editor showing the Execution tab with a Python function + + +## Test Run + +The **Test Run** button executes your code in isolation — no LLM involved — so you can verify inputs and outputs quickly. You can also call the test-execute endpoint directly from the API. + +```bash +curl -X POST https://api.promptlayer.com/api/public/v2/tool-registry/get_weather/test-execute \ + -H "X-API-KEY: $PROMPTLAYER_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"inputs": {"location": "San Francisco"}}' +``` + +The response includes `status`, `result`, `stdout`, `stderr`, and `duration_ms`. + +## Supported providers + +Auto-execution works with all providers that support tool/function calling: + +| Provider | Supported | +|----------|-----------| +| OpenAI Chat Completions | ✓ | +| OpenAI Responses API | ✓ | +| Anthropic | ✓ | +| Google Gemini | ✓ | +| Vertex AI | ✓ | +| Amazon Bedrock | ✓ | +| Mistral | ✓ | +| Cohere | ✓ | + +## Auto-execute badge + +In the Playground and Prompt Registry tool picker, tools with execution code show an **auto-execute** badge. When you run a prompt with one of these tools selected, the execution loop activates automatically. + +## API + +See the [Tool Registry API reference](/api-reference/tool-registry) for: +- `POST /api/public/v2/tool-registry` — create a tool with execution code (`execution` field) +- `POST /api/public/v2/tool-registry/{identifier}/versions` — add a version with execution code +- `POST /api/public/v2/tool-registry/{identifier}/test-execute` — test execution without an LLM diff --git a/openapi.json b/openapi.json index 474a3fe..abbedbf 100644 --- a/openapi.json +++ b/openapi.json @@ -7434,6 +7434,16 @@ "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." + }, + "description": { + "type": "string", + "nullable": true, + "description": "Human-readable summary of the tool, shown in the tool page header." + }, + "execution": { + "$ref": "#/components/schemas/ToolExecutionConfig", + "nullable": true, + "description": "Optional executable code for the initial version. When present, PromptLayer will auto-run this code whenever the LLM calls the tool." } } } @@ -7558,11 +7568,41 @@ }, "version": { "type": "object", - "nullable": true + "nullable": true, + "description": "The resolved tool version.", + "properties": { + "id": { + "type": "integer" + }, + "number": { + "type": "integer" + }, + "tool_definition": { + "type": "object" + }, + "execution": { + "$ref": "#/components/schemas/ToolExecutionConfig", + "nullable": true, + "description": "Execution config attached to this version, if any." + }, + "commit_message": { + "type": "string", + "nullable": true + }, + "user_id": { + "type": "integer", + "nullable": true + } + } }, "tool_definition": { "type": "object", "nullable": true + }, + "description": { + "type": "string", + "nullable": true, + "description": "Human-readable summary of the tool." } } } @@ -9630,30 +9670,2147 @@ } } } - }, + }, + "responses": { + "201": { + "description": "Trace added to draft dataset.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddTraceToDatasetResponse" + }, + "examples": { + "added": { + "summary": "Trace added successfully", + "value": { + "success": true, + "draft_dataset_id": 789, + "mode": "trace" + } + } + } + } + } + }, + "400": { + "description": "Invalid request (e.g. dataset not found, wrong workspace, or schema error).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "403": { + "$ref": "#/components/responses/ForbiddenError" + }, + "404": { + "description": "Trace not found in the workspace.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tool-registry/{identifier}/versions": { + "post": { + "tags": [ + "tool-registry" + ], + "summary": "Create Tool Version", + "description": "Create a new version for an existing tool. The tool can be identified by its numeric ID or name.", + "operationId": "create_tool_version", + "parameters": [ + { + "name": "identifier", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "Tool ID (numeric) or name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tool_definition" + ], + "properties": { + "tool_definition": { + "type": "object", + "description": "Tool definition in OpenAI function-calling format" + }, + "execution": { + "$ref": "#/components/schemas/ToolExecutionConfig", + "nullable": true, + "description": "Optional executable code. When present, PromptLayer auto-runs this code whenever the LLM calls the tool." + }, + "commit_message": { + "type": "string", + "nullable": true, + "description": "Commit message describing what changed in this version." + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Version created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "version": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "tool_registry_id": { + "type": "integer" + }, + "number": { + "type": "integer" + }, + "tool_definition": { + "type": "object" + }, + "execution": { + "$ref": "#/components/schemas/ToolExecutionConfig", + "nullable": true + }, + "commit_message": { + "type": "string", + "nullable": true + }, + "user_id": { + "type": "integer", + "nullable": true + } + } + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Tool not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tool-registry/{identifier}/test-execute": { + "post": { + "tags": [ + "tool-registry" + ], + "summary": "Test Execute Tool", + "description": "Test-run a tool's execution code against caller-provided inputs without an LLM in the loop. Useful for verifying tool code before attaching it to a version. Both `execution` and `tool_definition` are optional overrides \u2014 when present they take precedence over the saved version's stored config.", + "operationId": "test_execute_tool", + "parameters": [ + { + "name": "identifier", + "in": "path", + "required": true, + "schema": { + "type": "string", + "description": "Tool ID (numeric) or name" + } + }, + { + "name": "label", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "Resolve version by label name (e.g. 'production')" + } + }, + { + "name": "version", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "Resolve by specific version number" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "inputs": { + "type": "object", + "description": "Key-value pairs matching the tool's function parameters.", + "default": {} + }, + "execution": { + "$ref": "#/components/schemas/ToolExecutionConfig", + "nullable": true, + "description": "Override the version's stored execution config. Allows testing code without saving a new version first." + }, + "tool_definition": { + "type": "object", + "nullable": true, + "description": "Override the tool definition (used for function name resolution)." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Tool executed successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "result": { + "$ref": "#/components/schemas/ToolExecutionRunResult" + } + } + } + } + } + }, + "400": { + "description": "Bad request (missing execution config, missing function name, etc.)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Tool or version not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "502": { + "description": "Sandbox unavailable", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables": { + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Create Table", + "description": "Create a new Smart Table. A default sheet with one text column is created automatically.", + "operationId": "create_table", + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Table title. Defaults to a unique 'Untitled Table' name if omitted.", + "nullable": true + }, + "folder_id": { + "type": "integer", + "description": "Folder to place the table in.", + "nullable": true + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Table created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "table": { + "$ref": "#/components/schemas/SmartTableDetail" + } + } + } + } + } + }, + "400": { + "description": "Invalid request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Folder not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + }, + "get": { + "tags": [ + "smart-tables" + ], + "summary": "List Tables", + "description": "List Smart Tables in the workspace. Supports cursor-based pagination and optional filtering by folder or prompt column.", + "operationId": "list_tables", + "parameters": [ + { + "name": "folder_id", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "description": "Filter by folder ID." + } + }, + { + "name": "name", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "Filter by title (case-insensitive contains match)." + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string", + "description": "Pagination cursor from a previous response." + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "desc" + } + }, + { + "name": "prompt_id", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "description": "Filter to tables containing a column referencing this prompt." + } + }, + { + "name": "prompt_version_id", + "in": "query", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "prompt_label_id", + "in": "query", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "List of tables", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SmartTable" + } + }, + "next_cursor": { + "type": "string", + "nullable": true + }, + "has_more": { + "type": "boolean" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables/{table_id}": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "Get Table", + "operationId": "get_table", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Table detail", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "table": { + "$ref": "#/components/schemas/SmartTableDetail" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + }, + "patch": { + "tags": [ + "smart-tables" + ], + "summary": "Update Table", + "operationId": "update_table", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true + }, + "folder_id": { + "type": "integer", + "nullable": true + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Table updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "table": { + "$ref": "#/components/schemas/SmartTableDetail" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "List Sheets", + "description": "List all sheets in a table, ordered by their index.", + "operationId": "list_table_sheets", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "default": 20, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "prompt_id", + "in": "query", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "prompt_version_id", + "in": "query", + "required": false, + "schema": { + "type": "integer" + } + }, + { + "name": "prompt_label_id", + "in": "query", + "required": false, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "List of sheets", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SmartSheet" + } + }, + "next_cursor": { + "type": "string", + "nullable": true + }, + "has_more": { + "type": "boolean" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + }, + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Create Sheet", + "description": "Create a new sheet in a table by importing data from a file (CSV or JSON, base64-encoded) or from request log history.", + "operationId": "create_table_sheet", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "source" + ], + "properties": { + "title": { + "type": "string", + "nullable": true, + "description": "Sheet title. Defaults to the source file name or 'Request Logs'." + }, + "index": { + "type": "integer", + "nullable": true, + "description": "Display position within the table (0-based). Defaults to appending at the end." + }, + "operation_id": { + "type": "string", + "nullable": true, + "description": "Optional idempotency key for the import operation." + }, + "source": { + "description": "Data source for the sheet.", + "oneOf": [ + { + "type": "object", + "title": "File source", + "required": [ + "type", + "file_name", + "file_content_base64" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "file" + ] + }, + "file_name": { + "type": "string", + "description": "Original file name (must end in .csv or .json)." + }, + "file_content_base64": { + "type": "string", + "description": "Base64-encoded file content (max 100 MB)." + } + } + }, + { + "type": "object", + "title": "Request logs source", + "required": [ + "type" + ], + "properties": { + "type": { + "type": "string", + "enum": [ + "request_logs" + ] + }, + "request_log_ids": { + "type": "array", + "items": { + "type": "integer" + }, + "nullable": true, + "description": "Specific request log IDs to import. When omitted, filter params are used." + }, + "prompt_id": { + "type": "integer", + "nullable": true + }, + "prompt_version_id": { + "type": "integer", + "nullable": true + }, + "prompt_label_id": { + "type": "integer", + "nullable": true + }, + "start_time": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "end_time": { + "type": "string", + "format": "date-time", + "nullable": true + } + } + } + ] + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Import started. Poll the operation endpoint to track progress.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "message": { + "type": "string" + }, + "operation_id": { + "type": "string" + }, + "operation": { + "$ref": "#/components/schemas/SmartTableImportOperation" + }, + "sheet": { + "$ref": "#/components/schemas/SmartSheet" + } + } + } + } + } + }, + "400": { + "description": "Invalid request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/operations/{operation_id}": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "Get Sheet Import Operation", + "description": "Poll the status of an asynchronous sheet import operation.", + "operationId": "get_table_sheet_operation", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "operation_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Operation status", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "operation": { + "$ref": "#/components/schemas/SmartTableImportOperation" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Operation not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "Get Sheet", + "operationId": "get_table_sheet", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Sheet detail", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "sheet": { + "$ref": "#/components/schemas/SmartSheet" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "tags": [ + "smart-tables" + ], + "summary": "Update Sheet", + "operationId": "update_table_sheet", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true + }, + "index": { + "type": "integer", + "nullable": true, + "description": "New display position within the table (0-based)." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Sheet updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "sheet": { + "$ref": "#/components/schemas/SmartSheet" + }, + "version": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "List Columns", + "description": "List columns in a sheet, ordered by position rank.", + "operationId": "list_table_sheet_columns", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "default": 100, + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "List of columns", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SmartColumn" + } + }, + "next_cursor": { + "type": "string", + "nullable": true + }, + "has_more": { + "type": "boolean" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Create Column", + "description": "Add a new column to a sheet. Non-text columns will generate cells for all existing rows.", + "operationId": "create_table_sheet_column", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "title", + "type" + ], + "properties": { + "title": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "text", + "prompt_template", + "llm", + "code", + "score", + "comparison", + "composition" + ] + }, + "config": { + "type": "object", + "nullable": true, + "description": "Type-specific column configuration." + }, + "dependencies": { + "type": "array", + "nullable": true, + "description": "Column dependency edges for non-text columns.", + "items": { + "type": "object", + "required": [ + "column_id" + ], + "properties": { + "column_id": { + "type": "string", + "format": "uuid" + }, + "reference_type": { + "type": "string", + "default": "value" + }, + "config_key": { + "type": "string", + "nullable": true + }, + "config_meta": { + "type": "object", + "nullable": true + } + } + } + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Column created", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "column": { + "$ref": "#/components/schemas/SmartColumn" + }, + "cells": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SmartCell" + } + }, + "version": { + "type": "integer" + } + } + } + } + } + }, + "400": { + "description": "Cycle detected or invalid config", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns/{column_id}": { + "patch": { + "tags": [ + "smart-tables" + ], + "summary": "Update Column", + "description": "Update a column's title, config, or dependencies. Returns `requires_recalculation: true` when the change invalidates existing cell values.", + "operationId": "update_table_sheet_column", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "column_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "title": { + "type": "string", + "nullable": true + }, + "config": { + "type": "object", + "nullable": true + }, + "dependencies": { + "type": "array", + "nullable": true, + "items": { + "type": "object", + "required": [ + "column_id" + ], + "properties": { + "column_id": { + "type": "string", + "format": "uuid" + }, + "reference_type": { + "type": "string", + "default": "value" + }, + "config_key": { + "type": "string", + "nullable": true + }, + "config_meta": { + "type": "object", + "nullable": true + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Column updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "column": { + "$ref": "#/components/schemas/SmartColumn" + }, + "requires_recalculation": { + "type": "boolean" + }, + "affected_column_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + } + }, + "version": { + "type": "integer" + } + } + } + } + } + }, + "400": { + "description": "Cycle detected or invalid config", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table, sheet, or column not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/rows": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "List Rows", + "description": "List rows in a sheet, each containing a map of column_id \u2192 cell. Supports cursor pagination. Pass `include_columns=true` on the first page to receive column metadata alongside rows.", + "operationId": "list_table_sheet_rows", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "default": 100, + "minimum": 1, + "maximum": 100 + } + }, + { + "name": "order", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "asc", + "desc" + ], + "default": "asc" + } + }, + { + "name": "include_columns", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "description": "Include column metadata in the response. Defaults to true on the first page." + } + }, + { + "name": "include_row_count", + "in": "query", + "required": false, + "schema": { + "type": "boolean", + "default": true + } + } + ], + "responses": { + "200": { + "description": "List of rows", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "description": "Each item represents one row.", + "items": { + "type": "object", + "properties": { + "row_index": { + "type": "integer" + }, + "cells": { + "type": "object", + "description": "Map of column_id (UUID string) \u2192 cell object.", + "additionalProperties": { + "$ref": "#/components/schemas/SmartCell" + } + } + } + } + }, + "next_cursor": { + "type": "string", + "nullable": true + }, + "has_more": { + "type": "boolean" + }, + "row_count": { + "type": "integer" + }, + "columns": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SmartColumn" + } + }, + "version": { + "type": "integer" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Add Rows", + "description": "Append one or more rows to a sheet. Text column values can be set immediately; non-text column cells are created with `stale` status and must be triggered via a recalculation.", + "operationId": "add_table_sheet_rows", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "description": "Number of rows to append (1\u2013100).", + "default": 1, + "minimum": 1, + "maximum": 100 + }, + "values": { + "type": "array", + "nullable": true, + "description": "Per-row initial values for text columns. Each element is a map of column_id \u2192 value.", + "items": { + "type": "object", + "additionalProperties": true + } + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Rows added", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "rows_created": { + "type": "integer" + }, + "start_row_index": { + "type": "integer" + }, + "row_indices": { + "type": "array", + "items": { + "type": "integer" + } + }, + "rows": { + "type": "array", + "items": { + "type": "object", + "properties": { + "row_index": { + "type": "integer" + }, + "cells": { + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/SmartCell" + } + } + } + } + }, + "cell_count": { + "type": "integer" + }, + "row_count": { + "type": "integer" + }, + "version": { + "type": "integer" + } + } + } + } + } + }, + "400": { + "description": "No columns defined", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table or sheet not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationError" + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/{cell_id}": { + "get": { + "tags": [ + "smart-tables" + ], + "summary": "Get Cell", + "operationId": "get_table_sheet_cell", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cell_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Cell detail", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "cell": { + "$ref": "#/components/schemas/SmartCell" + } + } + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Cell not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + }, + "patch": { + "tags": [ + "smart-tables" + ], + "summary": "Update Cell", + "description": "Edit the value of a text column cell. Only cells in `text` type columns can be edited directly.", + "operationId": "update_table_sheet_cell", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cell_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "display_value": { + "type": "string", + "nullable": true, + "description": "Human-readable display value." + }, + "value": { + "description": "Structured value to store." + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Cell updated", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "cell": { + "$ref": "#/components/schemas/SmartCell" + }, + "version": { + "type": "integer" + }, + "stale_count": { + "type": "integer", + "description": "Number of downstream cells marked stale due to this edit." + } + } + } + } + } + }, + "400": { + "description": "Cell is not a text column cell", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Cell not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/recalculations": { + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Recalculate Cells (Batch)", + "description": "Trigger recalculation for a batch of cells identified by ID.", + "operationId": "create_table_sheet_cell_recalculations_batch", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "cell_ids" + ], + "properties": { + "cell_ids": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "description": "List of cell IDs to recalculate." + } + } + } + } + } + }, + "responses": { + "202": { + "description": "Recalculation started", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "execution_id": { + "type": "string" + }, + "cell_count": { + "type": "integer" + }, + "selected_cell_count": { + "type": "integer" + } + } + } + } + } + }, + "200": { + "description": "No cells to recalculate", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "$ref": "#/components/responses/UnauthorizedError" + }, + "404": { + "description": "Table, sheet, or cells not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + } + } + } + }, + "/api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/{cell_id}/recalculations": { + "post": { + "tags": [ + "smart-tables" + ], + "summary": "Recalculate Cell", + "description": "Trigger recalculation for a single cell.", + "operationId": "create_table_sheet_cell_recalculation", + "parameters": [ + { + "name": "table_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "sheet_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "cell_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid" + } + } + ], "responses": { - "201": { - "description": "Trace added to draft dataset.", + "202": { + "description": "Recalculation started", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AddTraceToDatasetResponse" - }, - "examples": { - "added": { - "summary": "Trace added successfully", - "value": { - "success": true, - "draft_dataset_id": 789, - "mode": "trace" + "type": "object", + "properties": { + "success": { + "type": "boolean" + }, + "execution_id": { + "type": "string" + }, + "cell_count": { + "type": "integer" } } } } } }, - "400": { - "description": "Invalid request (e.g. dataset not found, wrong workspace, or schema error).", + "200": { + "description": "No cells to recalculate", "content": { "application/json": { "schema": { @@ -9665,11 +11822,8 @@ "401": { "$ref": "#/components/responses/UnauthorizedError" }, - "403": { - "$ref": "#/components/responses/ForbiddenError" - }, "404": { - "description": "Trace not found in the workspace.", + "description": "Table, sheet, or cell not found", "content": { "application/json": { "schema": { @@ -9677,9 +11831,6 @@ } } } - }, - "422": { - "$ref": "#/components/responses/ValidationError" } } } @@ -18029,6 +20180,309 @@ "description": "Indicates whether the row was created from a full trace root (`trace`) or a specific span subtree (`span`)." } } + }, + "ToolExecutionConfig": { + "type": "object", + "required": [ + "type", + "language", + "code" + ], + "description": "Executable code attached to a tool version. When present, PromptLayer automatically runs this code whenever the LLM calls the tool.", + "properties": { + "type": { + "type": "string", + "enum": [ + "code" + ], + "description": "Execution type \u2014 currently only 'code' is supported." + }, + "language": { + "type": "string", + "enum": [ + "python", + "javascript" + ], + "description": "Programming language for the execution code." + }, + "code": { + "type": "string", + "description": "The function body to execute. Must define a function whose name matches the tool's function name." + } + } + }, + "ToolExecutionRunResult": { + "type": "object", + "description": "Result returned by the test-execute endpoint.", + "required": [ + "status", + "duration_ms" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "success", + "error" + ], + "description": "'success' if the function returned a value; 'error' if it raised an exception." + }, + "result": { + "description": "The value returned by the tool function (any JSON-serializable type). Null on error." + }, + "stdout": { + "type": "string", + "description": "Standard output captured during execution." + }, + "stderr": { + "type": "string", + "description": "Standard error captured during execution." + }, + "duration_ms": { + "type": "integer", + "description": "Execution time in milliseconds." + }, + "error": { + "type": "object", + "nullable": true, + "description": "Error details when status is 'error'." + } + } + }, + "SmartTable": { + "type": "object", + "description": "A Smart Table \u2014 a versioned, multi-sheet table that can run LLM columns to generate or evaluate data at scale.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Unique table identifier." + }, + "workspace_id": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "folder_id": { + "type": "integer", + "nullable": true + }, + "sheet_count": { + "type": "integer", + "description": "Number of active sheets." + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "SmartTableDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/SmartTable" + } + ], + "type": "object", + "properties": { + "sheet_row_counts": { + "type": "object", + "description": "Map of sheet_id \u2192 row count.", + "additionalProperties": { + "type": "integer" + } + } + } + }, + "SmartSheet": { + "type": "object", + "description": "A sheet within a Smart Table.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "table_id": { + "type": "string", + "format": "uuid" + }, + "workspace_id": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "index": { + "type": "integer", + "description": "Display order of the sheet within the table (0-based)." + }, + "row_count": { + "type": "integer" + }, + "version_count": { + "type": "integer" + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, + "SmartColumn": { + "type": "object", + "description": "A column within a Smart Table sheet.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "sheet_id": { + "type": "string", + "format": "uuid" + }, + "workspace_id": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "type": { + "type": "string", + "description": "Column type. 'text' columns store free-text; 'prompt_template', 'llm', 'code', 'score', 'comparison', and 'composition' columns run automated computations.", + "enum": [ + "text", + "prompt_template", + "llm", + "code", + "score", + "comparison", + "composition" + ] + }, + "config": { + "type": "object", + "description": "Type-specific configuration. Shape depends on the column type." + }, + "position_rank": { + "type": "number", + "description": "Fractional position rank used for ordering." + }, + "is_output_column": { + "type": "boolean" + } + } + }, + "SmartCell": { + "type": "object", + "description": "A single cell at the intersection of a column and a row.", + "properties": { + "id": { + "type": "string", + "format": "uuid" + }, + "sheet_id": { + "type": "string", + "format": "uuid" + }, + "column_id": { + "type": "string", + "format": "uuid" + }, + "row_index": { + "type": "integer" + }, + "status": { + "type": "string", + "enum": [ + "completed", + "stale", + "running", + "queued", + "error", + "cancelled" + ], + "description": "Current computation status of the cell." + }, + "display_value": { + "type": "string", + "nullable": true + }, + "value": { + "description": "Structured cell value (type depends on column type)." + }, + "error": { + "type": "string", + "nullable": true + } + } + }, + "SmartTableImportOperation": { + "type": "object", + "description": "Status of an asynchronous sheet import operation.", + "properties": { + "operation_id": { + "type": "string" + }, + "source": { + "type": "string", + "enum": [ + "file", + "request_logs" + ] + }, + "status": { + "type": "string", + "enum": [ + "pending", + "running", + "completed", + "failed" + ] + }, + "progress": { + "type": "number", + "nullable": true + }, + "message": { + "type": "string", + "nullable": true + }, + "rows_added": { + "type": "integer", + "nullable": true + }, + "row_count": { + "type": "integer", + "nullable": true + }, + "file_name": { + "type": "string", + "nullable": true + }, + "error_message": { + "type": "string", + "nullable": true + }, + "created_at": { + "type": "string", + "format": "date-time", + "nullable": true + }, + "updated_at": { + "type": "string", + "format": "date-time", + "nullable": true + } + } } }, "responses": { diff --git a/reference/table-sheet-cells-get.mdx b/reference/table-sheet-cells-get.mdx new file mode 100644 index 0000000..e8156c8 --- /dev/null +++ b/reference/table-sheet-cells-get.mdx @@ -0,0 +1,8 @@ +--- +title: "Get Cell" +openapi: "GET /api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/{cell_id}" +--- + +Retrieve a single cell by ID, including its current status, display value, and structured value. + +Cell statuses: `completed`, `stale`, `running`, `queued`, `error`, `cancelled`. diff --git a/reference/table-sheet-cells-recalculate-batch.mdx b/reference/table-sheet-cells-recalculate-batch.mdx new file mode 100644 index 0000000..e552497 --- /dev/null +++ b/reference/table-sheet-cells-recalculate-batch.mdx @@ -0,0 +1,8 @@ +--- +title: "Recalculate Cells (Batch)" +openapi: "POST /api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/recalculations" +--- + +Trigger recalculation for a batch of cells by ID. Returns `202 Accepted` with an `execution_id`. + +Use this endpoint to kick off computation for specific cells after adding rows or updating text cell values. diff --git a/reference/table-sheet-cells-recalculate.mdx b/reference/table-sheet-cells-recalculate.mdx new file mode 100644 index 0000000..5d0ee3e --- /dev/null +++ b/reference/table-sheet-cells-recalculate.mdx @@ -0,0 +1,6 @@ +--- +title: "Recalculate Cell" +openapi: "POST /api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/{cell_id}/recalculations" +--- + +Trigger recalculation for a single cell. Returns `202 Accepted` with an `execution_id` that can be used to track progress. diff --git a/reference/table-sheet-cells-update.mdx b/reference/table-sheet-cells-update.mdx new file mode 100644 index 0000000..408932e --- /dev/null +++ b/reference/table-sheet-cells-update.mdx @@ -0,0 +1,8 @@ +--- +title: "Update Cell" +openapi: "PATCH /api/public/v2/tables/{table_id}/sheets/{sheet_id}/cells/{cell_id}" +--- + +Edit the value of a text column cell. Only cells in `text` type columns can be edited directly — non-text column cells are computed automatically. + +Editing a cell marks downstream dependent cells as `stale`. diff --git a/reference/table-sheet-columns-create.mdx b/reference/table-sheet-columns-create.mdx new file mode 100644 index 0000000..7aef10f --- /dev/null +++ b/reference/table-sheet-columns-create.mdx @@ -0,0 +1,8 @@ +--- +title: "Create Column" +openapi: "POST /api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns" +--- + +Add a new column to a sheet. For non-text columns, cells for all existing rows are created with `stale` status and queued for computation. + +Use `dependencies` to declare which other columns this column's config references. PromptLayer enforces a DAG (no cycles allowed) and uses the dependency graph to propagate staleness when upstream cells change. diff --git a/reference/table-sheet-columns-list.mdx b/reference/table-sheet-columns-list.mdx new file mode 100644 index 0000000..46cd00a --- /dev/null +++ b/reference/table-sheet-columns-list.mdx @@ -0,0 +1,10 @@ +--- +title: "List Columns" +openapi: "GET /api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns" +--- + +List all columns in a sheet, ordered by their position rank. + +Each column has a `type` that determines how its cells are populated: +- `text` — Free-text cells, editable directly. +- `prompt_template`, `llm`, `code`, `score`, `comparison`, `composition` — Computed columns that run automatically. diff --git a/reference/table-sheet-columns-update.mdx b/reference/table-sheet-columns-update.mdx new file mode 100644 index 0000000..3c46944 --- /dev/null +++ b/reference/table-sheet-columns-update.mdx @@ -0,0 +1,8 @@ +--- +title: "Update Column" +openapi: "PATCH /api/public/v2/tables/{table_id}/sheets/{sheet_id}/columns/{column_id}" +--- + +Update a column's title, config, or dependencies. + +When the change invalidates existing cell values (e.g., the prompt template or code changes), the response includes `requires_recalculation: true` and the list of `affected_column_ids`. diff --git a/reference/table-sheet-rows-add.mdx b/reference/table-sheet-rows-add.mdx new file mode 100644 index 0000000..1bd6fa6 --- /dev/null +++ b/reference/table-sheet-rows-add.mdx @@ -0,0 +1,8 @@ +--- +title: "Add Rows" +openapi: "POST /api/public/v2/tables/{table_id}/sheets/{sheet_id}/rows" +--- + +Append one or more rows (up to 100 at a time) to a sheet. + +Text column values can be set immediately via the `values` array. Non-text column cells are created with `stale` status — trigger a [recalculation](/reference/table-sheet-cells-recalculate) to compute them. diff --git a/reference/table-sheet-rows-list.mdx b/reference/table-sheet-rows-list.mdx new file mode 100644 index 0000000..bd3b37b --- /dev/null +++ b/reference/table-sheet-rows-list.mdx @@ -0,0 +1,10 @@ +--- +title: "List Rows" +openapi: "GET /api/public/v2/tables/{table_id}/sheets/{sheet_id}/rows" +--- + +List rows in a sheet. Each row contains a map of `column_id → cell`. + +Pass `include_columns=true` (the default on the first page) to receive column metadata alongside rows — useful for building column headers. + +Use cursor-based pagination for large sheets. diff --git a/reference/table-sheets-create.mdx b/reference/table-sheets-create.mdx new file mode 100644 index 0000000..9e03ef0 --- /dev/null +++ b/reference/table-sheets-create.mdx @@ -0,0 +1,9 @@ +--- +title: "Create Sheet" +openapi: "POST /api/public/v2/tables/{table_id}/sheets" +--- + +Create a new sheet in a table by importing data. Two source types are supported: + +- **file** — Upload a CSV or JSON file (base64-encoded, max 100 MB). The import runs asynchronously; poll the operation endpoint to track progress. +- **request_logs** — Import from your PromptLayer request history. Filter by prompt, version, label, or date range. diff --git a/reference/table-sheets-get-operation.mdx b/reference/table-sheets-get-operation.mdx new file mode 100644 index 0000000..1a08a09 --- /dev/null +++ b/reference/table-sheets-get-operation.mdx @@ -0,0 +1,6 @@ +--- +title: "Get Sheet Import Operation" +openapi: "GET /api/public/v2/tables/{table_id}/sheets/operations/{operation_id}" +--- + +Poll the status of an asynchronous sheet import operation. The `operation_id` is returned when a sheet is created via the [Create Sheet](/reference/table-sheets-create) endpoint. diff --git a/reference/table-sheets-get.mdx b/reference/table-sheets-get.mdx new file mode 100644 index 0000000..ae9ae21 --- /dev/null +++ b/reference/table-sheets-get.mdx @@ -0,0 +1,6 @@ +--- +title: "Get Sheet" +openapi: "GET /api/public/v2/tables/{table_id}/sheets/{sheet_id}" +--- + +Retrieve a single sheet by ID, including its current row count. diff --git a/reference/table-sheets-list.mdx b/reference/table-sheets-list.mdx new file mode 100644 index 0000000..56482df --- /dev/null +++ b/reference/table-sheets-list.mdx @@ -0,0 +1,6 @@ +--- +title: "List Sheets" +openapi: "GET /api/public/v2/tables/{table_id}/sheets" +--- + +List all sheets in a table, ordered by their index (display position). diff --git a/reference/table-sheets-update.mdx b/reference/table-sheets-update.mdx new file mode 100644 index 0000000..783f46f --- /dev/null +++ b/reference/table-sheets-update.mdx @@ -0,0 +1,6 @@ +--- +title: "Update Sheet" +openapi: "PATCH /api/public/v2/tables/{table_id}/sheets/{sheet_id}" +--- + +Update a sheet's title or display index (position within the table). diff --git a/reference/tables-create.mdx b/reference/tables-create.mdx new file mode 100644 index 0000000..c19016a --- /dev/null +++ b/reference/tables-create.mdx @@ -0,0 +1,8 @@ +--- +title: "Create Table" +openapi: "POST /api/public/v2/tables" +--- + +Create a new Smart Table. A default sheet with one text column is created automatically. + +Smart Tables are versioned, multi-sheet tables that can run LLM, code, and comparison columns to generate or evaluate data at scale. diff --git a/reference/tables-get.mdx b/reference/tables-get.mdx new file mode 100644 index 0000000..f5cede1 --- /dev/null +++ b/reference/tables-get.mdx @@ -0,0 +1,6 @@ +--- +title: "Get Table" +openapi: "GET /api/public/v2/tables/{table_id}" +--- + +Retrieve a single Smart Table by ID, including its sheet count and per-sheet row counts. diff --git a/reference/tables-list.mdx b/reference/tables-list.mdx new file mode 100644 index 0000000..3ef7f01 --- /dev/null +++ b/reference/tables-list.mdx @@ -0,0 +1,6 @@ +--- +title: "List Tables" +openapi: "GET /api/public/v2/tables" +--- + +List Smart Tables in the workspace. Supports cursor-based pagination. Filter by folder, title, or by prompt columns that reference specific prompts. diff --git a/reference/tables-update.mdx b/reference/tables-update.mdx new file mode 100644 index 0000000..412a816 --- /dev/null +++ b/reference/tables-update.mdx @@ -0,0 +1,6 @@ +--- +title: "Update Table" +openapi: "PATCH /api/public/v2/tables/{table_id}" +--- + +Update a Smart Table's title or folder. diff --git a/reference/tool-registry-create-version.mdx b/reference/tool-registry-create-version.mdx new file mode 100644 index 0000000..34e295a --- /dev/null +++ b/reference/tool-registry-create-version.mdx @@ -0,0 +1,8 @@ +--- +title: "Create Tool Version" +openapi: "POST /api/public/v2/tool-registry/{identifier}/versions" +--- + +Create a new version for an existing tool. The `identifier` can be a numeric tool ID or a tool name. + +Each version is immutable and assigned an incrementing version number. Include an `execution` object to attach Python or JavaScript code that PromptLayer will auto-run whenever the LLM calls this tool — see [Auto-Execution](/features/tool-registry/auto-execution). diff --git a/reference/tool-registry-test-execute.mdx b/reference/tool-registry-test-execute.mdx new file mode 100644 index 0000000..6c0e459 --- /dev/null +++ b/reference/tool-registry-test-execute.mdx @@ -0,0 +1,10 @@ +--- +title: "Test Execute Tool" +openapi: "POST /api/public/v2/tool-registry/{identifier}/test-execute" +--- + +Test a tool's execution code against caller-provided inputs without involving the LLM. Useful for verifying that your tool code works before saving a version or using it in production. + +You can pass an `execution` override to test unsaved code, or a `tool_definition` override to test a different function name. When neither is provided, the stored execution config for the resolved version is used. + +See [Auto-Execution](/features/tool-registry/auto-execution) for how execution code works end-to-end. From c26e5be5ea313c1fd34c76befca392bafbef5384 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 21 May 2026 13:53:26 +0000 Subject: [PATCH 2/2] Remove tool auto-execution docs (covered by separate author PR) Reverts openapi.json and docs.json changes for PR #917 (tool auto-execution): - Remove ToolExecutionConfig and ToolExecutionRunResult schemas - Remove execution/description additions to tool-registry create/get - Remove /versions and /test-execute tool-registry endpoints - Remove auto-execution feature guide and reference pages from nav Keeps Smart Tables API documentation (PR #932) unchanged. https://claude.ai/code/session_01Gomnn5WphRge7nVT8BbMKr --- docs.json | 5 +- features/tool-registry/auto-execution.mdx | 93 ------ openapi.json | 347 +-------------------- reference/tool-registry-create-version.mdx | 8 - reference/tool-registry-test-execute.mdx | 10 - 5 files changed, 2 insertions(+), 461 deletions(-) delete mode 100644 features/tool-registry/auto-execution.mdx delete mode 100644 reference/tool-registry-create-version.mdx delete mode 100644 reference/tool-registry-test-execute.mdx diff --git a/docs.json b/docs.json index 9fe0d2f..fdac864 100644 --- a/docs.json +++ b/docs.json @@ -100,8 +100,7 @@ "pages": [ "features/tool-registry/overview", "features/tool-registry/using-in-prompts", - "features/tool-registry/save-inline-to-registry", - "features/tool-registry/auto-execution" + "features/tool-registry/save-inline-to-registry" ], "icon": "wrench" }, @@ -305,8 +304,6 @@ "reference/tool-registry-list", "reference/tool-registry-get", "reference/tool-registry-create", - "reference/tool-registry-create-version", - "reference/tool-registry-test-execute", "reference/external-ids-tool-registry-attach", "reference/external-ids-tool-registry-list", "reference/external-ids-tool-registry-delete" diff --git a/features/tool-registry/auto-execution.mdx b/features/tool-registry/auto-execution.mdx deleted file mode 100644 index bd868dd..0000000 --- a/features/tool-registry/auto-execution.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Auto-Execution" -icon: "bolt" ---- - -Auto-execution lets you attach Python or JavaScript code directly to a Tool Registry entry. When the LLM calls the tool, PromptLayer automatically runs your code in a secure sandbox, feeds the result back to the model, and continues the conversation — all without writing any client-side loop. - -## How it works - -1. A tool version stores a function schema *and* optional execution code (Python or JavaScript). -2. During inference — in the Playground, via the Prompt Registry, or through evaluations — PromptLayer detects tool calls where an executable version is selected. -3. The platform extracts the function arguments from the LLM response, runs the code, and appends the result as a `tool` message. -4. The LLM receives the result and continues. The loop repeats until the model stops calling executable tools, or until the iteration limit is reached. - -Each LLM call in the loop is logged as its own request, so the full trace is visible in your request history. - -## Writing execution code - -Your code must define a function whose name matches the `name` field in the tool's function schema. - -**Python example** - -```python -def get_weather(location: str) -> dict: - import urllib.request, json - url = f"https://wttr.in/{location}?format=j1" - with urllib.request.urlopen(url) as resp: - data = json.load(resp) - return {"temperature": data["current_condition"][0]["temp_C"], "unit": "C"} -``` - -**JavaScript example** - -```javascript -async function get_weather(location) { - const resp = await fetch(`https://wttr.in/${location}?format=j1`); - const data = await resp.json(); - return { temperature: data.current_condition[0].temp_C, unit: "C" }; -} -``` - -The function receives the LLM's tool call arguments as keyword arguments (Python) or an object (JavaScript). Whatever you return is serialised to JSON and sent back to the model. - -## Adding execution code in the UI - -1. Open a tool in the Tool Registry. -2. Click **Edit → New Version**. -3. Switch to the **Execution** tab next to the schema editor. -4. Write your Python or JavaScript function. -5. Use **Test Run** to verify it works before saving. - - - Tool registry editor showing the Execution tab with a Python function - - -## Test Run - -The **Test Run** button executes your code in isolation — no LLM involved — so you can verify inputs and outputs quickly. You can also call the test-execute endpoint directly from the API. - -```bash -curl -X POST https://api.promptlayer.com/api/public/v2/tool-registry/get_weather/test-execute \ - -H "X-API-KEY: $PROMPTLAYER_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"inputs": {"location": "San Francisco"}}' -``` - -The response includes `status`, `result`, `stdout`, `stderr`, and `duration_ms`. - -## Supported providers - -Auto-execution works with all providers that support tool/function calling: - -| Provider | Supported | -|----------|-----------| -| OpenAI Chat Completions | ✓ | -| OpenAI Responses API | ✓ | -| Anthropic | ✓ | -| Google Gemini | ✓ | -| Vertex AI | ✓ | -| Amazon Bedrock | ✓ | -| Mistral | ✓ | -| Cohere | ✓ | - -## Auto-execute badge - -In the Playground and Prompt Registry tool picker, tools with execution code show an **auto-execute** badge. When you run a prompt with one of these tools selected, the execution loop activates automatically. - -## API - -See the [Tool Registry API reference](/api-reference/tool-registry) for: -- `POST /api/public/v2/tool-registry` — create a tool with execution code (`execution` field) -- `POST /api/public/v2/tool-registry/{identifier}/versions` — add a version with execution code -- `POST /api/public/v2/tool-registry/{identifier}/test-execute` — test execution without an LLM diff --git a/openapi.json b/openapi.json index abbedbf..d95d1c0 100644 --- a/openapi.json +++ b/openapi.json @@ -7434,16 +7434,6 @@ "$ref": "#/components/schemas/ExternalId" }, "description": "Identifiers from other systems." - }, - "description": { - "type": "string", - "nullable": true, - "description": "Human-readable summary of the tool, shown in the tool page header." - }, - "execution": { - "$ref": "#/components/schemas/ToolExecutionConfig", - "nullable": true, - "description": "Optional executable code for the initial version. When present, PromptLayer will auto-run this code whenever the LLM calls the tool." } } } @@ -7568,41 +7558,11 @@ }, "version": { "type": "object", - "nullable": true, - "description": "The resolved tool version.", - "properties": { - "id": { - "type": "integer" - }, - "number": { - "type": "integer" - }, - "tool_definition": { - "type": "object" - }, - "execution": { - "$ref": "#/components/schemas/ToolExecutionConfig", - "nullable": true, - "description": "Execution config attached to this version, if any." - }, - "commit_message": { - "type": "string", - "nullable": true - }, - "user_id": { - "type": "integer", - "nullable": true - } - } + "nullable": true }, "tool_definition": { "type": "object", "nullable": true - }, - "description": { - "type": "string", - "nullable": true, - "description": "Human-readable summary of the tool." } } } @@ -9724,243 +9684,6 @@ } } }, - "/api/public/v2/tool-registry/{identifier}/versions": { - "post": { - "tags": [ - "tool-registry" - ], - "summary": "Create Tool Version", - "description": "Create a new version for an existing tool. The tool can be identified by its numeric ID or name.", - "operationId": "create_tool_version", - "parameters": [ - { - "name": "identifier", - "in": "path", - "required": true, - "schema": { - "type": "string", - "description": "Tool ID (numeric) or name" - } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "required": [ - "tool_definition" - ], - "properties": { - "tool_definition": { - "type": "object", - "description": "Tool definition in OpenAI function-calling format" - }, - "execution": { - "$ref": "#/components/schemas/ToolExecutionConfig", - "nullable": true, - "description": "Optional executable code. When present, PromptLayer auto-runs this code whenever the LLM calls the tool." - }, - "commit_message": { - "type": "string", - "nullable": true, - "description": "Commit message describing what changed in this version." - } - } - } - } - } - }, - "responses": { - "201": { - "description": "Version created", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean" - }, - "version": { - "type": "object", - "properties": { - "id": { - "type": "integer" - }, - "tool_registry_id": { - "type": "integer" - }, - "number": { - "type": "integer" - }, - "tool_definition": { - "type": "object" - }, - "execution": { - "$ref": "#/components/schemas/ToolExecutionConfig", - "nullable": true - }, - "commit_message": { - "type": "string", - "nullable": true - }, - "user_id": { - "type": "integer", - "nullable": true - } - } - } - } - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "description": "Tool not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "$ref": "#/components/responses/ValidationError" - } - } - } - }, - "/api/public/v2/tool-registry/{identifier}/test-execute": { - "post": { - "tags": [ - "tool-registry" - ], - "summary": "Test Execute Tool", - "description": "Test-run a tool's execution code against caller-provided inputs without an LLM in the loop. Useful for verifying tool code before attaching it to a version. Both `execution` and `tool_definition` are optional overrides \u2014 when present they take precedence over the saved version's stored config.", - "operationId": "test_execute_tool", - "parameters": [ - { - "name": "identifier", - "in": "path", - "required": true, - "schema": { - "type": "string", - "description": "Tool ID (numeric) or name" - } - }, - { - "name": "label", - "in": "query", - "required": false, - "schema": { - "type": "string", - "description": "Resolve version by label name (e.g. 'production')" - } - }, - { - "name": "version", - "in": "query", - "required": false, - "schema": { - "type": "string", - "description": "Resolve by specific version number" - } - } - ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "inputs": { - "type": "object", - "description": "Key-value pairs matching the tool's function parameters.", - "default": {} - }, - "execution": { - "$ref": "#/components/schemas/ToolExecutionConfig", - "nullable": true, - "description": "Override the version's stored execution config. Allows testing code without saving a new version first." - }, - "tool_definition": { - "type": "object", - "nullable": true, - "description": "Override the tool definition (used for function name resolution)." - } - } - } - } - } - }, - "responses": { - "200": { - "description": "Tool executed successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "success": { - "type": "boolean" - }, - "message": { - "type": "string" - }, - "result": { - "$ref": "#/components/schemas/ToolExecutionRunResult" - } - } - } - } - } - }, - "400": { - "description": "Bad request (missing execution config, missing function name, etc.)", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "401": { - "$ref": "#/components/responses/UnauthorizedError" - }, - "404": { - "description": "Tool or version not found", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "502": { - "description": "Sandbox unavailable", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ErrorResponse" - } - } - } - }, - "422": { - "$ref": "#/components/responses/ValidationError" - } - } - } - }, "/api/public/v2/tables": { "post": { "tags": [ @@ -20181,74 +19904,6 @@ } } }, - "ToolExecutionConfig": { - "type": "object", - "required": [ - "type", - "language", - "code" - ], - "description": "Executable code attached to a tool version. When present, PromptLayer automatically runs this code whenever the LLM calls the tool.", - "properties": { - "type": { - "type": "string", - "enum": [ - "code" - ], - "description": "Execution type \u2014 currently only 'code' is supported." - }, - "language": { - "type": "string", - "enum": [ - "python", - "javascript" - ], - "description": "Programming language for the execution code." - }, - "code": { - "type": "string", - "description": "The function body to execute. Must define a function whose name matches the tool's function name." - } - } - }, - "ToolExecutionRunResult": { - "type": "object", - "description": "Result returned by the test-execute endpoint.", - "required": [ - "status", - "duration_ms" - ], - "properties": { - "status": { - "type": "string", - "enum": [ - "success", - "error" - ], - "description": "'success' if the function returned a value; 'error' if it raised an exception." - }, - "result": { - "description": "The value returned by the tool function (any JSON-serializable type). Null on error." - }, - "stdout": { - "type": "string", - "description": "Standard output captured during execution." - }, - "stderr": { - "type": "string", - "description": "Standard error captured during execution." - }, - "duration_ms": { - "type": "integer", - "description": "Execution time in milliseconds." - }, - "error": { - "type": "object", - "nullable": true, - "description": "Error details when status is 'error'." - } - } - }, "SmartTable": { "type": "object", "description": "A Smart Table \u2014 a versioned, multi-sheet table that can run LLM columns to generate or evaluate data at scale.", diff --git a/reference/tool-registry-create-version.mdx b/reference/tool-registry-create-version.mdx deleted file mode 100644 index 34e295a..0000000 --- a/reference/tool-registry-create-version.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Create Tool Version" -openapi: "POST /api/public/v2/tool-registry/{identifier}/versions" ---- - -Create a new version for an existing tool. The `identifier` can be a numeric tool ID or a tool name. - -Each version is immutable and assigned an incrementing version number. Include an `execution` object to attach Python or JavaScript code that PromptLayer will auto-run whenever the LLM calls this tool — see [Auto-Execution](/features/tool-registry/auto-execution). diff --git a/reference/tool-registry-test-execute.mdx b/reference/tool-registry-test-execute.mdx deleted file mode 100644 index 6c0e459..0000000 --- a/reference/tool-registry-test-execute.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: "Test Execute Tool" -openapi: "POST /api/public/v2/tool-registry/{identifier}/test-execute" ---- - -Test a tool's execution code against caller-provided inputs without involving the LLM. Useful for verifying that your tool code works before saving a version or using it in production. - -You can pass an `execution` override to test unsaved code, or a `tool_definition` override to test a different function name. When neither is provided, the stored execution config for the resolved version is used. - -See [Auto-Execution](/features/tool-registry/auto-execution) for how execution code works end-to-end.